Seemingly dellivelink.py works properly now, though
[dwarf-doc.git] / dwarf5 / latexdoc / examples.tex
1 \chapter{Examples (Informative)}
2 \label{app:examplesinformative}F
3
4 The following sections provide examples that illustrate
5 various aspects of the DWARF debugging information format.
6
7
8 \section{ Compilation Units and Abbreviations Table Example}F
9 \label{app:compilationunitsandabbreviationstableexample}
10
11
12 Figure \refersec{fig:compilationunitsandabbreviationstable}
13 depicts the relationship of the abbreviations tables contained
14 \addtoindexx{abbreviations table!example}
15 \addtoindexx{\texttt{.debug\_abbrev}!example}
16 \addtoindexx{\texttt{.debug\_info}!example}
17 in the \dotdebugabbrev{}
18 section to the information contained in
19 the \dotdebuginfo{}
20 section. Values are given in symbolic form,
21 where possible.
22
23 The figure corresponds to the following two trivial source files:
24
25 File myfile.c
26 \begin{lstlisting}[numbers=none]
27 typedef char* POINTER;
28 \end{lstlisting}
29 File myfile2.c
30 \begin{lstlisting}[numbers=none]
31 typedef char* strp;
32 \end{lstlisting}
33
34 % Ensures we get the following float out before we go on.
35 \clearpage
36 \begin{figure}[here]
37 %\centering
38 %\setlength{\linewidth}{1.1\linewidth}
39 \begin{minipage}[t]{0.03\linewidth}
40 \flushright
41 \scriptsize
42 % Note: alltt is used to step down the needed number of lines to the labels
43 \begin{alltt}
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64 \textit{e1:}
65
66
67
68
69 \textit{e2:}
70 \end{alltt}
71 \end{minipage}
72 %
73 \begin{minipage}[t]{0.38\linewidth}
74 \centering
75 Compilation Unit \#1: \dotdebuginfo{}
76 \begin{framed}
77 \scriptsize
78 \begin{alltt}
79 \textit{length}
80 4
81 \textit{a1 (abbreviations table offset)}
82 4
83 \vspace{0.01cm}
84 \hrule
85 1
86 "myfile.c"
87 "Best Compiler Corp, V1.3"
88 "/home/mydir/src"
89 \livelink{chap:DWLANGC89}{DW\_LANG\_C89}
90 0x0
91 0x55
92 \livelink{chap:DWFORMsecoffset}{DW\_FORM\_sec\_offset}
93 0x0
94 \vspace{0.01cm}
95 \hrule
96 2
97 "char"
98 \livelink{chap:DWATEunsignedchar}{DW\_ATE\_unsigned\_char}
99 1
100 \vspace{0.01cm}
101 \hrule
102 3
103 \textit{e1  (debug info offset)}
104 \vspace{0.01cm}
105 \hrule
106 4
107 "POINTER"
108 \textit{e2  (debug info offset)}
109 \vspace{0.01cm}
110 \hrule
111 0
112 \end{alltt}
113 %
114 %
115 \end{framed}
116 Compilation Unit \#2: \dotdebuginfo{}
117 \begin{framed}
118 \scriptsize
119 \begin{alltt}
120 \textit{length}
121 4
122 \textit{a1 (abbreviations table offset)}
123 4
124 \vspace{0.01cm}
125 \hrule
126 ...
127 \vspace{0.01cm}
128 \hrule
129 4
130 "strp"
131 \textit{e2  (debug info offset)}
132 \vspace{0.01cm}
133 \hrule
134 ...
135 \end{alltt}
136 %
137 %
138 \end{framed}
139 \end{minipage}
140 \hfill 
141 % Place the label for the abbreviation table
142 \begin{minipage}[t]{0.03\linewidth}
143 \flushright
144 \scriptsize
145 % Note: alltt is used to step down the needed number of lines to the label
146 \begin{alltt}
147
148
149
150
151
152 \textit{a1:}
153 \end{alltt}
154 \end{minipage}
155 %
156 \begin{minipage}[t]{0.41\linewidth}
157 \centering
158 Abbreviation Table: \dotdebugabbrev{}
159 \begin{framed}
160 \scriptsize
161 \begin{alltt}\vspace{0.06cm}
162 1
163 \livelink{chap:DWTAGcompileunit}{DW\_TAG\_compile\_unit}
164 \livelink{chap:DWCHILDRENyes}{DW\_CHILDREN\_yes}
165 \livelink{chap:DWATname}{DW\_AT\_name}       \livelink{chap:DWFORMstring}{DW\_FORM\_string}
166 \livelink{chap:DWATproducer}{DW\_AT\_producer}   \livelink{chap:DWFORMstring}{DW\_FORM\_string}
167 \livelink{chap:DWATcompdir}{DW\_AT\_comp\_dir}   \livelink{chap:DWFORMstring}{DW\_FORM\_string}
168 \livelink{chap:DWATlanguage}{DW\_AT\_language}   \livelink{chap:DWFORMdata1}{DW\_FORM\_data1}
169 \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}     \livelink{chap:DWFORMaddr}{DW\_FORM\_addr}
170 \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}    \livelink{chap:DWFORMdata1}{DW\_FORM\_data1}
171 \livelink{chap:DWATstmtlist}{DW\_AT\_stmt\_list}  \livelink{chap:DWFORMindirect}{DW\_FORM\_indirect}
172 0
173 \vspace{0.01cm}
174 \hrule
175 2
176 \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
177 \livelink{chap:DWCHILDRENno}{DW\_CHILDREN\_no}
178 \livelink{chap:DWATname}{DW\_AT\_name}       \livelink{chap:DWFORMstring}{DW\_FORM\_string}
179 \livelink{chap:DWATencoding}{DW\_AT\_encoding}   \livelink{chap:DWFORMdata1}{DW\_FORM\_data1}
180 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}  \livelink{chap:DWFORMdata1}{DW\_FORM\_data1}
181 0
182 \vspace{0.01cm}
183 \hrule
184 3
185 \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type}
186 \livelink{chap:DWCHILDRENno}{DW\_CHILDREN\_no}
187 \livelink{chap:DWATtype}{DW\_AT\_type}       \livelink{chap:DWFORMref4}{DW\_FORM\_ref4}
188 0
189 \vspace{0.01cm}
190 \hrule
191 4
192 \livelink{chap:DWTAGtypedef}{DW\_TAG\_typedef}
193 \livelink{chap:DWCHILDRENno}{DW\_CHILDREN\_no}
194 \livelink{chap:DWATname}{DW\_AT\_name}      \livelink{chap:DWFORMstring}{DW\_FORM\_string}
195 \livelink{chap:DWATtype}{DW\_AT\_type}      \livelink{chap:DWFORMrefaddr}{DW\_FORM\_ref\_addr}
196 0
197 \vspace{0.01cm}
198 \hrule
199 0
200 \end{alltt}
201 \end{framed}
202 \end{minipage}
203
204 \vspace{0.2cm}
205 \caption{Compilation units and abbreviations table} \label{fig:compilationunitsandabbreviationstable}
206 \end{figure}
207
208 % Ensures we get the above float out before we go on.
209 \clearpage
210
211 \section{Aggregate Examples}
212 \label{app:aggregateexamples}
213
214 The following examples illustrate how to represent some of
215 the more complicated forms of array and record aggregates
216 using DWARF.
217
218 \subsection{Fortran Array Example}
219 \label{app:fortranarrayexample}
220 Consider the \addtoindex{Fortran array}\addtoindexx{Fortran 90} source fragment in 
221 \addtoindexx{array type entry!examples}
222 Figure \referfol{fig:fortranarrayexamplesourcefragment}.
223
224 \begin{figure}[here]
225 \begin{lstlisting}
226 type array_ptr
227 real :: myvar
228 real, dimension (:), pointer :: ap
229 end type array_ptr
230 type(array_ptr), allocatable, dimension(:) :: arrayvar
231 allocate(arrayvar(20))
232 do i = 1, 20
233 allocate(arrayvar(i)%ap(i+10))
234 end do
235 \end{lstlisting}
236 \caption{Fortran array example: source fragment} \label{fig:fortranarrayexamplesourcefragment}
237 \end{figure}
238
239 For allocatable and pointer arrays, it is essentially required
240 by the \addtoindex{Fortran array} semantics that each array consist of 
241 \addtoindexx{descriptor!array}
242 two
243 \addtoindexx{array!descriptor for}
244 parts, which we here call 1) the descriptor and 2) the raw
245 data. (A descriptor has often been called a dope vector in
246 other contexts, although it is often a structure of some kind
247 rather than a simple vector.) Because there are two parts,
248 and because the lifetime of the descriptor is necessarily
249 longer than and includes that of the raw data, there must be
250 an address somewhere in the descriptor that points to the
251 raw data when, in fact, there is some (that is, when 
252 the \doublequote{variable} is allocated or associated).
253
254 For concreteness, suppose that a descriptor looks something
255 like the C structure in 
256 Figure \refersec{fig:fortranarrayexampledescriptorrepresentation}.
257 Note, however, that it is
258 a property of the design that 1) a debugger needs no builtin
259 knowledge of this structure and 2) there does not need to
260 be an explicit representation of this structure in the DWARF
261 input to the debugger.
262
263 \begin{figure}[here]
264 \begin{lstlisting}
265 struct desc {
266     long el_len;       // Element length
267     void * base;       // Address of raw data
268     int ptr_assoc : 1; // Pointer is associated flag
269     int ptr_alloc : 1; // Pointer is allocated flag
270     int num_dims  : 6; // Number of dimensions
271     struct dims_str {  // For each dimension...  
272         long low_bound;
273         long upper_bound;
274         long stride;
275     } dims[63];
276 };
277 \end{lstlisting}
278 \caption{Fortran array example: descriptor representation}
279 \label{fig:fortranarrayexampledescriptorrepresentation}
280 \end{figure}
281
282
283 In practice, of course, a \doublequote{real} descriptor will have
284 dimension substructures only for as many dimensions as are
285 specified in the \texttt{num\_dims} component. Let us use the notation
286 \texttt{desc\textless n\textgreater}   
287 to indicate a specialization of the \texttt{desc} struct in
288 which \texttt{n} is the bound for the \texttt{dims} component as well as the
289 contents of the \texttt{num\_dims} component.
290
291 Because the arrays considered here come in two parts, it is
292 necessary to distinguish the parts carefully. In particular,
293 the \doublequote{address of the variable} or equivalently, the \doublequote{base
294 address of the object} \emph{always} refers to the descriptor. For
295 arrays that do not come in two parts, an implementation can
296 provide a descriptor anyway, thereby giving it two parts. (This
297 may be convenient for general runtime support unrelated to
298 debugging.) In this case the above vocabulary applies as
299 stated. Alternatively, an implementation can do without a
300 descriptor, in which case the \doublequote{address of the variable,}
301 or equivalently the \doublequote{base address of the object}, refers
302 to the \doublequote{raw data} (the real data, the only thing around
303 that can be the object).
304
305 If an object has a descriptor, then the DWARF type for that
306 object will have a 
307 \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location} 
308 attribute. If an object
309 does not have a descriptor, then usually the DWARF type for the
310 object will not have a 
311 \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location}. 
312 (See the following
313 \addtoindex{Ada} example for a case where the type for an object without
314 a descriptor does have a 
315 \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location} attribute. In
316 that case the object doubles as its own descriptor.)
317
318 The \addtoindex{Fortran} derived type \texttt{array\_ptr} can now be redescribed
319 in C\dash like terms that expose some of the representation as in
320
321 \begin{lstlisting}[numbers=none]
322 struct array_ptr {
323     float myvar;
324     desc<1> ap;
325 };
326 \end{lstlisting}
327
328 Similarly for variable \texttt{arrayvar}:
329 \begin{lstlisting}[numbers=none]
330 desc<1> arrayvar;
331 \end{lstlisting}
332
333 (Recall that \texttt{desc\textless 1\textgreater} 
334 indicates the 1\dash dimensional version of \texttt{desc}.)
335
336 \newpage
337 Finally, the following notation is useful:
338 \begin{enumerate}[1. ]
339 \item  sizeof(type): size in bytes of entities of the given type
340 \item offset(type, comp): offset in bytes of the comp component
341 within an entity of the given type
342 \end{enumerate}
343
344 The DWARF description is shown 
345 \addtoindexx{Fortran 90}
346 in Figure \refersec{fig:fortranarrayexampledwarfdescription}.
347
348 \begin{figure}[h]
349 \figurepart{1}{2}
350 \begin{dwflisting}
351 \begin{alltt}
352 ! Description for type of 'ap'
353 !
354 1\$: \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type}
355         ! No name, default (Fortran) ordering, default stride
356         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to REAL)
357         \livelink{chap:DWATassociated}{DW\_AT\_associated}(expression= ! Test 'ptr\_assoc' \nolink{flag}
358             \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
359             \DWOPlitn              ! where n == offset(ptr\_assoc)
360             \livelink{chap:DWOPplus}{DW\_OP\_plus}
361             \livelink{chap:DWOPderef}{DW\_OP\_deref}
362             \livelink{chap:DWOPlit1}{DW\_OP\_lit1}              ! mask for 'ptr\_assoc' \nolink{flag}
363             \livelink{chap:DWOPand}{DW\_OP\_and})
364         \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location}(expression= ! Get raw data address
365             \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
366             \DWOPlitn              ! where n == offset(base)
367             \livelink{chap:DWOPplus}{DW\_OP\_plus}
368             \livelink{chap:DWOPderef}{DW\_OP\_deref})            ! Type of index of array 'ap'
369 2\$:     \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
370             ! No name, default stride
371             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to INTEGER)
372             \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}(expression=
373                 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
374                 \DWOPlitn          ! where n ==
375                                     !   offset(desc, dims) +
376                                     !   offset(dims\_str, lower\_bound)
377                 \livelink{chap:DWOPplus}{DW\_OP\_plus}
378                 \livelink{chap:DWOPderef}{DW\_OP\_deref})
379             \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(expression=
380                 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
381                 \DWOPlitn          ! where n ==
382                                     !   offset(desc, dims) +
383                                     !   offset(dims\_str, upper\_bound)
384                 \livelink{chap:DWOPplus}{DW\_OP\_plus}
385                 \livelink{chap:DWOPderef}{DW\_OP\_deref})
386             !  Note: for the m'th dimension, the second operator becomes
387             !  \DWOPlitn where
388             !       n == offset(desc, dims)          +
389             !                (m-1)*sizeof(dims\_str)  +
390             !                 offset(dims\_str, [lower|upper]\_bound)
391             !  That is, the expression does not get longer for each successive 
392             !  dimension (other than to express the larger offsets involved).
393 \end{alltt}
394 \end{dwflisting}
395 \caption{Fortran array example: DWARF description}
396 \label{fig:fortranarrayexampledwarfdescription}
397 \end{figure}
398
399 \begin{figure}
400 \figurepart{2}{2}
401 \begin{dwflisting}
402 \begin{alltt}
403 3\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
404         \livelink{chap:DWATname}{DW\_AT\_name}("array\_ptr")
405         \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}(constant sizeof(REAL) + sizeof(desc<1>))
406 4\$:     \livelink{chap:DWTAGmember}{DW\_TAG\_member}
407             \livelink{chap:DWATname}{DW\_AT\_name}("myvar")
408             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to REAL)
409             \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}(constant 0)
410 5\$:     \livelink{chap:DWTAGmember}{DW\_TAG\_member}
411             \livelink{chap:DWATname}{DW\_AT\_name}("ap");
412             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
413             \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}(constant sizeof(REAL))
414 6\$: \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type}
415         ! No name, default (Fortran) ordering, default stride
416         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 3\$)
417         \livelink{chap:DWATallocated}{DW\_AT\_allocated}(expression=     ! Test 'ptr\_alloc' \nolink{flag}
418             \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
419             \DWOPlitn                  ! where n == offset(ptr\_alloc)
420             \livelink{chap:DWOPplus}{DW\_OP\_plus}
421             \livelink{chap:DWOPderef}{DW\_OP\_deref}
422             \DWOPlittwo                  ! Mask for 'ptr\_alloc' \nolink{flag}
423             \livelink{chap:DWOPand}{DW\_OP\_and})
424         \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location}(expression= ! Get raw data address
425             \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
426             \DWOPlitn                  ! where n == offset(base)
427             \livelink{chap:DWOPplus}{DW\_OP\_plus}
428             \livelink{chap:DWOPderef}{DW\_OP\_deref})
429 7\$:     \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
430             ! No name, default stride
431             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to INTEGER)
432             \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}(expression=
433                 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
434                 \DWOPlitn              ! where n == ...
435                 \livelink{chap:DWOPplus}{DW\_OP\_plus}
436                 \livelink{chap:DWOPderef}{DW\_OP\_deref})
437             \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(expression=
438                 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
439                 \DWOPlitn              ! where n == ...
440                 \livelink{chap:DWOPplus}{DW\_OP\_plus}
441                 \livelink{chap:DWOPderef}{DW\_OP\_deref})
442 8\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
443         \livelink{chap:DWATname}{DW\_AT\_name}("arrayvar")
444         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 6\$)
445         \livelink{chap:DWATlocation}{DW\_AT\_location}(expression=
446             ...as appropriate...)       ! Assume static allocation
447 \end{alltt}
448 \end{dwflisting}
449 \begin{center}
450
451 Figure~\ref{fig:fortranarrayexampledwarfdescription} Fortran array example: DWARF description \textit{(concluded)}
452 \end{center}
453 \end{figure}
454
455 Suppose 
456 \addtoindexx{Fortran array example}
457 the program is stopped immediately following completion
458 of the do loop. Suppose further that the user enters the
459 following debug command:
460
461 \begin{lstlisting}[numbers=none]
462 debug> print arrayvar(5)%ap(2)
463 \end{lstlisting}
464
465 Interpretation of this expression proceeds as follows:
466 \begin{enumerate}[1. ]
467
468 \item Lookup name \texttt{arrayvar}. We find that it is a variable,
469 whose type is given by the unnamed type at 6\$. Notice that
470 the type is an array type.
471
472
473 \item Find the 5$^{th}$ element of that array object. To do array
474 indexing requires several pieces of information:
475 \begin{enumerate}[a) ]
476
477 \item  the address of the array data
478
479 \item the lower bounds of the array \\
480 % Using plain [] here gives trouble.
481 \lbrack To check that 5 is within bounds would require the upper
482 bound too, but we will skip that for this example. \rbrack
483
484 \item the stride 
485
486 \end{enumerate}
487
488 For a), check for a 
489 \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location} attribute. 
490 Since there is one, go execute the expression, whose result is
491 the address needed. The object address used in this case
492 is the object we are working on, namely the variable named
493 \texttt{arrayvar}, whose address was found in step 1. (Had there been
494 no \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location} attribute, the desired address would
495 be the same as the address from step 1.)
496
497 For b), for each dimension of the array (only one
498 in this case), go interpret the usual lower bound
499 attribute. Again this is an expression, which again begins
500 with \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}. This object is 
501 \textbf{still} \texttt{arrayvar},
502 from step 1, because we have not begun to actually perform
503 any indexing yet.
504
505 For c), the default stride applies. Since there is no
506 \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride} attribute, use the size of the array element
507 type, which is the size of type \texttt{array\_ptr} (at 3\$).
508
509 \clearpage
510
511 Having acquired all the necessary data, perform the indexing
512 operation in the usual manner--which has nothing to do with
513 any of the attributes involved up to now. Those just provide
514 the actual values used in the indexing step.
515
516 The result is an object within the memory that was dynamically
517 allocated for \texttt{arrayvar}.
518
519 \item  Find the \texttt{ap} component of the object just identified,
520 whose type is \texttt{array\_ptr}.
521
522 This is a conventional record component lookup and
523 interpretation. It happens that the \texttt{ap} component in this case
524 begins at offset 4 from the beginning of the containing object.
525 Component \texttt{ap} has the unnamed array type defined at 1\$ in the
526 symbol table.
527
528 \item  Find the second element of the array object found in step 3. To do array indexing requires
529 several pieces of information:
530 \begin{enumerate}[a) ]
531 \item  the address of the array storage
532
533 \item  the lower bounds of the array \\
534 % Using plain [] here gives trouble.
535 \lbrack To check that 2 is within bounds we would require the upper
536 bound too, but we will skip that for this example \rbrack
537
538 \item  the stride
539
540 \end{enumerate}
541 \end{enumerate}
542
543 This is just like step 2), so the details are omitted. Recall
544 that because the DWARF type 1\$ has a \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location},
545 the address that results from step 4) is that of a
546 descriptor, and that address is the address pushed by the
547 \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address} operations in 1\$ and 2\$.
548
549 Note: we happen to be accessing a pointer array here instead
550 of an allocatable array; but because there is a common
551 underlying representation, the mechanics are the same. There
552 could be completely different descriptor arrangements and the
553 mechanics would still be the same---only the stack machines
554 would be different.
555
556 %\needlines{8}
557 \subsection{Fortran Coarray Examples}
558 \label{app:Fortrancoarrayexamples}
559
560 \subsubsection{Fortran Scalar Coarray Example}
561 The \addtoindex{Fortran} scalar coarray example
562 \addtoindexx{coarray!example}\addtoindexx{scalar coarray|see{coarray}}
563 in Figure \refersec{fig:Fortranscalarcoarraysourcefragment} can be described as 
564 illustrated in Figure \refersec{fig:FortranscalarcoarrayDWARFdescription}.
565
566 \begin{figure}[!h]
567 \begin{lstlisting}
568         INTEGER X[*]
569 \end{lstlisting}
570 \caption{Fortran scalar coarray: source fragment}
571 \label{fig:Fortranscalarcoarraysourcefragment}
572 \end{figure}
573
574 \begin{figure}[!h]
575 \begin{dwflisting}
576 \begin{alltt}
577 10\$:  \DWTAGcoarraytype
578         \DWATtype(reference to INTEGER)
579         \DWTAGsubrangetype                ! Note omitted upper bound                    
580             \DWATlowerbound(constant 1)
581
582 11\$:  \DWTAGvariable
583         \DWATname("X")
584         \DWATtype(reference to coarray type at 10\$)
585 \end{alltt}
586 \end{dwflisting}
587 \caption{Fortran scalar coarray: DWARF description}
588 \label{fig:FortranscalarcoarrayDWARFdescription}
589 \end{figure}
590
591 \subsubsection{Fortran Array Coarray Example}
592 The \addtoindex{Fortran} (simple) array coarray example
593 \addtoindexx{coarray!example}\addtoindexx{array coarray|see{coarray}}
594 in Figure \refersec{fig:Fortranarraycoarraysourcefragment} can be described as 
595 illustrated in Figure \refersec{fig:FortranarraycoarrayDWARFdescription}.
596
597 \begin{figure}[here]
598 \begin{lstlisting}
599         INTEGER X(10)[*]
600 \end{lstlisting}
601 \caption{Fortran array coarray: source fragment}
602 \label{fig:Fortranarraycoarraysourcefragment}
603 \end{figure}
604
605 \begin{figure}[here]
606 \begin{dwflisting}
607 \begin{alltt}
608 10\$: \DWTAGarraytype
609         \DWATordering(\DWORDcolmajor)
610         \DWATtype(reference to INTEGER)
611 11\$:    \DWTAGsubrangetype
612             \DWATlowerbound(constant 1)
613             \DWATupperbound(constant 10)
614
615 12\$: \DWTAGcoarraytype
616         \DWATtype(reference to array type at 10\$)
617 13\$:    \DWTAGsubrangetype                ! Note omitted upper bound
618             \DWATlowerbound(constant 1)
619
620 14$: \DWTAGvariable
621         \DWATname("X")
622         \DWATtype(reference to coarray type at 12\$)
623 \end{alltt}
624 \end{dwflisting}
625 \caption{Fortran array coarray: DWARF description}
626 \label{fig:FortranarraycoarrayDWARFdescription}
627 \end{figure}
628
629 \subsubsection{Fortran Multidimensional Coarray Example}
630 The \addtoindex{Fortran} multidimensional coarray of a multidimensional array example
631 \addtoindexx{coarray!example}\addtoindexx{array coarray|see{coarray}}
632 in Figure \refersec{fig:Fortranmultidimensionalcoarraysourcefragment} can be described as 
633 illustrated in Figure \refersec{fig:FortranmultidimensionalcoarrayDWARFdescription}.
634
635 \begin{figure}[here]
636 \begin{lstlisting}
637         INTEGER X(10,11,12)[2,3,*]
638 \end{lstlisting}
639 \caption{Fortran multidimentional coarray: source fragment}
640 \label{fig:Fortranmultidimensionalcoarraysourcefragment}
641 \end{figure}
642
643 \begin{figure}[here]
644 \begin{dwflisting}
645 \begin{alltt}
646 10\$: \DWTAGarraytype
647         \DWATordering(\DWORDcolmajor)
648         \DWATtype(reference to INTEGER)
649 11\$:    \DWTAGsubrangetype
650             \DWATlowerbound(constant 1)
651             \DWATupperbound(constant 10)
652 12\$:    \DWTAGsubrangetype
653             \DWATlowerbound(constant  1)
654             \DWATupperbound(constant 11)
655 13\$:    \DWTAGsubrangetype
656             \DWATlowerbound(constant  1)
657             \DWATupperbound(constant 12)
658
659 14\$: \DWTAGcoarraytype
660         \DWATtype(reference to array_type at 10\$)
661 15\$:    \DWTAGsubrangetype
662             \DWATlowerbound(constant 1)
663             \DWATupperbound(constant 2)
664 16\$:    \DWTAGsubrangetype
665             \DWATlowerbound(constant 1)
666             \DWATupperbound(constant 3)
667 17\$:    \DWTAGsubrangetype                ! Note omitted upper bound
668             \DWATlowerbound(constant 1)
669
670 18\$: \DWTAGvariable
671         \DWATname("X")
672         \DWATtype(reference to coarray type at 14\$)
673 \end{alltt}
674 \end{dwflisting}
675 \caption{Fortran multidimensional coarray: DWARF description}
676 \label{fig:FortranmultidimensionalcoarrayDWARFdescription}
677 \end{figure}
678
679
680 \clearpage
681 \subsection{Fortran 2008 Assumed-rank Array Example}
682 \label{app:assumedrankexample}
683 \addtoindexx{array!assumed-rank}
684 Consider the example in Figure~\ref{fig:assumedrankdecl}, which shows
685 an assumed-rank array in Fortran~2008 with
686 supplement~29113:\footnote{Technical Specification ISO/IEC TS
687   29113:2012 \emph{Further Interoperability of Fortran with C}}
688
689 \begin{figure}[!h]
690 \begin{lstlisting}
691   subroutine foo(x)
692     real :: x(..)
693
694     ! x has n dimensions
695   
696   end subroutine
697 \end{lstlisting}
698 \caption{Declaration of a Fortran 2008 assumed-rank array}
699 \label{fig:assumedrankdecl}
700 \end{figure}
701
702 Let's assume the Fortran compiler used an array descriptor that
703 (in \addtoindex{C}) looks
704 like the one shown in Figure~\ref{fig:arraydesc}.
705
706 \begin{figure}[!h]
707 \begin{lstlisting}
708   struct array_descriptor {
709     void *base_addr;
710     int rank;
711     struct dim dims[]; 
712   }
713
714   struct dim {
715      int lower_bound;
716      int upper_bound;
717      int stride;
718      int flags;
719   }
720 \end{lstlisting}
721 \caption{One of many possible layouts for an array descriptor}
722 \label{fig:arraydesc}
723 \end{figure}
724
725 The DWARF type for the array \emph{x} can be described as shown in
726 Figure~\refersec{fig:assumedrankdwarf}.
727
728 \begin{figure}[!h]
729 \begin{dwflisting}
730 \begin{alltt}
731 10\$:  \DWTAGarraytype
732          \DWATtype(reference to real)
733          \DWATrank(expression=
734              \DWOPpushobjectaddress
735              \DWOPlitn                ! offset of rank in descriptor>
736              \DWOPplus
737              \DWOPderef)
738          \DWATdatalocation(expression=
739              \DWOPpushobjectaddress
740              \DWOPlitn                ! offset of data in descriptor>
741              \DWOPplus
742              \DWOPderef)
743 11\$:    \DWTAGgenericsubrange
744              \DWATtype(reference to integer)
745              \DWATlowerbound(expression=
746              !   Looks up the lower bound of dimension i.
747              !   Operation                           ! Stack effect
748              !   (implicit)                          ! i                                                                     
749                  \DWOPlitn                          ! i sizeof(dim)
750                  \DWOPmul                           ! dim[i]
751                  \DWOPlitn                          ! dim[i] offsetof(dim)
752                  \DWOPplus                          ! dim[i]+offset
753                  \DWOPpushobjectaddress           ! dim[i]+offsetof(dim) objptr
754                  \DWOPplus                          ! objptr.dim[i]
755                  \DWOPlitn                          ! objptr.dim[i] offsetof(lb)
756                  \DWOPplus                          ! objptr.dim[i].lowerbound
757                  \DWOPderef)                        ! *objptr.dim[i].lowerbound
758              \DWATupperbound(expression=
759              !   Looks up the upper bound of dimension i.
760                  \DWOPlitn                          ! sizeof(dim)
761                  \DWOPmul
762                  \DWOPlitn                          ! offsetof(dim)
763                  \DWOPplus
764                  \DWOPpushobjectaddress
765                  \DWOPplus
766                  \DWOPlitn                          ! offset of upperbound in dim
767                  \DWOPplus
768                  \DWOPderef)
769              \DWATbytestride(expression=
770              !   Looks up the byte stride of dimension i.
771                  ...
772              !   (analogous to DW\_AT\_upper\_bound)
773                  )
774 \end{alltt}
775 \end{dwflisting}
776 \caption{Sample DWARF for the array descriptor in Figure~\ref{fig:arraydesc}}
777 \label{fig:assumedrankdwarf}
778 \end{figure}
779
780 The layout of the array descriptor is not specified by the Fortran
781 standard unless the array is explicitly marked as \addtoindex{C-interoperable}. To
782 get the bounds of an assumed-rank array, the expressions in the
783 \DWTAGgenericsubrange
784 entry need to be evaluated for each of the
785 \DWATrank{} dimensions as shown by the pseudocode in
786 Figure~\refersec{fig:assumedrankdwarfparser}.
787
788 \begin{figure}[!h]
789 \begin{lstlisting}
790     typedef struct {
791         int lower, upper, stride;
792     } dims_t;
793
794     typedef struct {
795         int rank;
796     struct dims_t *dims;
797     } array_t;
798
799     array_t get_dynamic_array_dims(DW_TAG_array a) {
800       array_t result;
801
802       // Evaluate the DW_AT_rank expression to get the 
803       //    number of dimensions.
804       dwarf_stack_t stack;
805       dwarf_eval(stack, a.rank_expr);
806       result.rank = dwarf_pop(stack); 
807       result.dims = new dims_t[rank];
808
809       // Iterate over all dimensions and find their bounds.
810       for (int i = 0; i < result.rank; i++) {
811         // Evaluate the generic subrange's DW_AT_lower 
812         //    expression for dimension i.
813         dwarf_push(stack, i);
814         assert( stack.size == 1 );
815         dwarf_eval(stack, a.generic_subrange.lower_expr);
816         result.dims[i].lower = dwarf_pop(stack);
817         assert( stack.size == 0 );
818
819         dwarf_push(stack, i);
820         dwarf_eval(stack, a.generic_subrange.upper_expr);
821         result.dims[i].upper = dwarf_pop(stack);
822     
823         dwarf_push(stack, i);
824         dwarf_eval(stack, a.generic_subrange.byte_stride_expr);
825         result.dims[i].stride = dwarf_pop(stack);
826       }
827       return result;
828     }
829 \end{lstlisting}
830 \caption{How to interpret the DWARF from Figure~\ref{fig:assumedrankdwarf}}
831 \label{fig:assumedrankdwarfparser}
832 \end{figure}
833
834
835
836 \clearpage
837 \subsection{Ada Example}
838 \label{app:adaexample}
839 Figure \refersec{fig:adaexamplesourcefragment}
840 illustrates two kinds of \addtoindex{Ada} 
841 parameterized array, one embedded in a record.
842
843 \begin{figure}[here]
844 \begin{lstlisting}
845 M : INTEGER := <exp>;
846 VEC1 : array (1..M) of INTEGER;
847 subtype TEENY is INTEGER range 1..100;
848 type ARR is array (INTEGER range <>) of INTEGER;
849 type REC2(N : TEENY := 100) is record
850     VEC2 : ARR(1..N);
851 end record;
852
853 OBJ2B : REC2;
854 \end{lstlisting}
855 \caption{Ada example: source fragment}
856 \label{fig:adaexamplesourcefragment}
857 \end{figure}
858
859 \texttt{VEC1} illustrates an (unnamed) array type where the upper bound
860 of the first and only dimension is determined at runtime. 
861 \addtoindex{Ada}
862 semantics require that the value of an array bound is fixed at
863 the time the array type is elaborated (where \textit{elaboration} refers
864 to the runtime executable aspects of type processing). For
865 the purposes of this example, we assume that there are no
866 other assignments to \texttt{M} so that it safe for the \texttt{REC1} type
867 description to refer directly to that variable (rather than
868 a compiler-generated copy).
869
870 \texttt{REC2} illustrates another array type (the unnamed type of
871 component \texttt{VEC2}) where the upper bound of the first and only
872 bound is also determined at runtime. In this case, the upper
873 bound is contained in a discriminant of the containing record
874 type. (A \textit{discriminant} is a component of a record whose value
875 cannot be changed independently of the rest of the record
876 because that value is potentially used in the specification
877 of other components of the record.)
878
879 The DWARF description is shown in 
880 Figure \refersec{fig:adaexampledwarfdescription}.
881
882
883 Interesting aspects about this example are:
884 \begin{enumerate}[1. ]
885 \item The array \texttt{VEC2} is \doublequote{immediately} contained within structure
886 \texttt{REC2} (there is no intermediate descriptor or indirection),
887 which is reflected in the absence of a \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location}
888 attribute on the array type at 28\$.
889
890 \item One of the bounds of \texttt{VEC2} is nonetheless dynamic and part of
891 the same containing record. It is described as a reference to
892 a member, and the location of the upper bound is determined
893 as for any member. That is, the location is determined using
894 an address calculation relative to the base of the containing
895 object.  
896
897 A consumer must notice that the referenced bound is a
898 member of the same containing object and implicitly push the
899 base address of the containing object just as for accessing
900 a data member generally.
901
902 \item The lack of a subtype concept in DWARF means that DWARF types
903 serve the role of subtypes and must replicate information from
904 what should be the parent type. For this reason, DWARF for
905 the unconstrained array type \texttt{ARR} is not needed for the purposes
906 of this example and therefore is not shown.
907 \end{enumerate}
908
909 \begin{figure}[p]
910 \begin{dwflisting}
911 \begin{alltt}
912 11\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
913         \livelink{chap:DWATname}{DW\_AT\_name}("M")
914         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to INTEGER)
915 12\$: \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type}
916         ! No name, default (\addtoindex{Ada}) order, default stride
917         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to INTEGER)
918 13\$:    \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
919             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to INTEGER)
920             \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}(constant 1)
921             \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(reference to variable M at 11\$)
922 14\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
923         \livelink{chap:DWATname}{DW\_AT\_name}("VEC1")
924         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to array type at 12\$)
925      . . .
926 21\$: \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
927         \livelink{chap:DWATname}{DW\_AT\_name}("TEENY")
928         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to INTEGER)
929         \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}(constant 1)
930         \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(constant 100)
931      . . .
932 26\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
933         \livelink{chap:DWATname}{DW\_AT\_name}("REC2")
934 27\$:    \livelink{chap:DWTAGmember}{DW\_TAG\_member}
935             \livelink{chap:DWATname}{DW\_AT\_name}("N")
936             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to subtype TEENY at 21\$)
937             \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}(constant 0)
938 28\$:    \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type}
939             ! No name, default (\addtoindex{Ada}) order, default stride
940             ! Default data location
941             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to INTEGER)
942 29\$:        \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
943                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to subrange TEENY at 21\$)
944                 \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}(constant 1)
945                 \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(reference to member N at 27\$)
946 30\$:    \livelink{chap:DWTAGmember}{DW\_TAG\_member}
947             \livelink{chap:DWATname}{DW\_AT\_name}("VEC2")
948             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to array "subtype" at 28\$)
949             \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}(machine=
950                 \DWOPlitn                  ! where n == offset(REC2, VEC2)
951                 \livelink{chap:DWOPplus}{DW\_OP\_plus})
952      . . .
953 41\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
954         \livelink{chap:DWATname}{DW\_AT\_name}("OBJ2B")
955         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to REC2 at 26\$)
956         \livelink{chap:DWATlocation}{DW\_AT\_location}(...as appropriate...)
957 \end{alltt}
958 \end{dwflisting}
959 \caption{Ada example: DWARF description}
960 \label{fig:adaexampledwarfdescription}
961 \end{figure}
962
963 \clearpage
964
965 \subsection{Pascal Example}
966 \label{app:pascalexample}
967 The Pascal \addtoindexx{Pascal example} source in 
968 Figure \referfol{fig:packedrecordexamplesourcefragment}
969 is used to illustrate the representation of packed unaligned
970 \addtoindex{bit fields}.
971
972 \begin{figure}[here]
973 \begin{lstlisting}
974 TYPE T : PACKED RECORD                  ! bit size is 2
975          F5 : BOOLEAN;                  ! bit offset is 0
976          F6 : BOOLEAN;                  ! bit offset is 1
977          END;
978 VAR V :  PACKED RECORD
979          F1 : BOOLEAN;                  ! bit offset is 0
980          F2 : PACKED RECORD             ! bit offset is 1
981               F3 : INTEGER;             ! bit offset is 0 in F2, 1 in V
982               END;
983          F4 : PACKED ARRAY [0..1] OF T; ! bit offset is 33
984          F7 : T;                        ! bit offset is 37
985          END;
986 \end{lstlisting}
987 \caption{Packed record example: source fragment}
988 \label{fig:packedrecordexamplesourcefragment}
989 \end{figure}
990
991 The DWARF representation in 
992 Figure \refersec{fig:packedrecordexampledwarfdescription} 
993 is appropriate. 
994 \livelink{chap:DWTAGpackedtype}{DW\_TAG\_packed\_type} entries could be added to
995 better represent the source, but these do not otherwise affect
996 the example and are omitted for clarity. Note that this same
997 representation applies to both typical big\dash \ and 
998 little\dash endian
999 architectures using the conventions described in 
1000 Section \refersec{chap:datamemberentries}.
1001
1002 \begin{figure}[p]
1003 \figurepart{1}{2}
1004 \begin{dwflisting}
1005 \begin{alltt}
1006 10\$: \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
1007         \livelink{chap:DWATname}{DW\_AT\_name}("BOOLEAN")
1008             ...
1009 11\$: \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
1010         \livelink{chap:DWATname}{DW\_AT\_name}("INTEGER")
1011             ...
1012 20\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
1013         \livelink{chap:DWATname}{DW\_AT\_name}("T")
1014         \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(2)
1015         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1016             \livelink{chap:DWATname}{DW\_AT\_name}("F5")
1017             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 10$)
1018             \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}(0)        ! may be omitted
1019             \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(1)
1020         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1021             \livelink{chap:DWATname}{DW\_AT\_name}("F6")
1022             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 10$)
1023             \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}(1)
1024             \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(1)
1025 21\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}                  ! anonymous type for F2
1026         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1027             \livelink{chap:DWATname}{DW\_AT\_name}("F3")
1028             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 11\$)
1029 22\$: \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type}                      ! anonymous type for F4
1030         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 20\$)
1031         \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
1032             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 11\$)
1033             \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}(0)
1034             \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(1)
1035         \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride}(2)
1036         \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(4) \addtoindexx{bit size attribute}
1037 23\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}                  ! anonymous type for V
1038         \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(39) \addtoindexx{bit size attribute}
1039         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1040             \livelink{chap:DWATname}{DW\_AT\_name}("F1")
1041             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 10\$)
1042             \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}(0)        ! may be omitted
1043             \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(1) ! may be omitted
1044         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1045             \livelink{chap:DWATname}{DW\_AT\_name}("F2")
1046             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 21\$)
1047             \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}(1)
1048             \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(32) ! may be omitted
1049         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1050             \livelink{chap:DWATname}{DW\_AT\_name}("F4")
1051             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 22\$)
1052             \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}(33)
1053             \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(4) ! may be omitted
1054 \end{alltt}
1055 \end{dwflisting}
1056 \caption{Packed record example: DWARF description}
1057 \label{fig:packedrecordexampledwarfdescription}
1058 \end{figure}
1059
1060 \begin{figure}[p]
1061 \figurepart{2}{2}
1062 \begin{dwflisting}
1063 \begin{alltt}
1064         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1065             \livelink{chap:DWATname}{DW\_AT\_name}("F7")
1066             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 20\$)    ! type T
1067             \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}(37)
1068             \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(2) \addtoindexx{bit size attribute}              ! may be omitted
1069      \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1070         \livelink{chap:DWATname}{DW\_AT\_name}("V")
1071         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 23\$)
1072         \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
1073         ...
1074 \end{alltt}
1075 \end{dwflisting}
1076 \begin{center}
1077 Figure~\ref{fig:packedrecordexampledwarfdescription}: Packed record example: DWARF description \textit{(concluded)}
1078 \end{center}
1079 \end{figure}
1080
1081 \section{Namespace Example}
1082 \label{app:namespaceexample}
1083
1084 The \addtoindex{C++} example in 
1085 Figure \refersec{fig:namespaceexamplesourcefragment}
1086 is used 
1087 \addtoindexx{namespace (C++)!example}
1088 to illustrate the representation of namespaces.
1089 The DWARF representation in 
1090 Figure \refersec{fig:namespaceexampledwarfdescription}
1091 is appropriate.
1092
1093 \begin{figure}[p]
1094 \begin{lstlisting}
1095 namespace {
1096     int i;
1097 }
1098 namespace A {
1099     namespace B {
1100         int j;
1101         int   myfunc (int a);
1102         float myfunc (float f) { return f - 2.0; }
1103         int   myfunc2(int a)   { return a + 2; }
1104     }
1105 }
1106 namespace Y {
1107     using A::B::j;         // (1) using declaration
1108     int foo;
1109 }
1110 using A::B::j;             // (2) using declaration
1111 namespace Foo = A::B;      // (3) namespace alias
1112 using Foo::myfunc;         // (4) using declaration
1113 using namespace Foo;       // (5) using directive
1114 namespace A {
1115     namespace B {
1116         using namespace Y; // (6) using directive
1117         int k;
1118     }
1119 }
1120 int Foo::myfunc(int a)
1121 {
1122     i = 3;
1123     j = 4;
1124     return myfunc2(3) + j + i + a + 2;
1125 }
1126 \end{lstlisting}
1127 \caption{Namespace example: source fragment}
1128 \label{fig:namespaceexamplesourcefragment}
1129 \end{figure}
1130
1131
1132 \begin{figure}[p]
1133 \figurepart{1}{2}
1134 \begin{dwflisting}
1135 \begin{alltt}
1136
1137 1\$:  \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
1138         \livelink{chap:DWATname}{DW\_AT\_name}("int")
1139         ...
1140 2\$:  \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
1141         \livelink{chap:DWATname}{DW\_AT\_name}("float")
1142         ...
1143 6\$:  \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
1144         ! no \livelink{chap:DWATname}{DW\_AT\_name} attribute
1145 7\$:
1146         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1147             \livelink{chap:DWATname}{DW\_AT\_name}("i")
1148             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1149             \livelink{chap:DWATlocation}{DW\_AT\_location} ...
1150             ...
1151 10\$: \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
1152         \livelink{chap:DWATname}{DW\_AT\_name}("A")
1153 20\$:    \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
1154             \livelink{chap:DWATname}{DW\_AT\_name}("B")
1155 30\$:        \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1156                 \livelink{chap:DWATname}{DW\_AT\_name}("j")
1157                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1158                 \livelink{chap:DWATlocation}{DW\_AT\_location} ...
1159                 ...
1160 34\$:        \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1161                 \livelink{chap:DWATname}{DW\_AT\_name}("myfunc")
1162                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1163                 ...
1164 36\$:        \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1165                 \livelink{chap:DWATname}{DW\_AT\_name}("myfunc")
1166                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 2\$)
1167                 ...
1168 38\$:        \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1169                 \livelink{chap:DWATname}{DW\_AT\_name}("myfunc2")
1170                 \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} ...
1171                 \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc} ...
1172                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1173                 ...
1174 \end{alltt}
1175 \end{dwflisting}
1176 \caption{Namespace example: DWARF description}
1177 \label{fig:namespaceexampledwarfdescription}
1178 \end{figure}
1179
1180 \begin{figure}
1181 \figurepart{2}{2}
1182 \begin{dwflisting}
1183 \begin{alltt}
1184 40\$: \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
1185         \livelink{chap:DWATname}{DW\_AT\_name}("Y")
1186         \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}            ! (1) using-declaration
1187             \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 30\$)
1188         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1189             \livelink{chap:DWATname}{DW\_AT\_name}("foo")
1190             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1191             \livelink{chap:DWATlocation}{DW\_AT\_location} ...
1192             ...
1193      \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}               ! (2) using declaration
1194         \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 30\$)
1195         \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}            ! (3) namespace alias
1196             \livelink{chap:DWATname}{DW\_AT\_name}("Foo")
1197             \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 20\$)
1198         \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}            ! (4) using declaration
1199             \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 34\$)     !     - part 1
1200         \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}            ! (4) using declaration
1201             \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 36\$)     !     - part 2
1202         \livelink{chap:DWTAGimportedmodule}{DW\_TAG\_imported\_module}                 ! (5) using directive
1203             \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 20\$)
1204         \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
1205             \livelink{chap:DWATextension}{DW\_AT\_extension}(reference to 10\$)
1206             \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
1207                 \livelink{chap:DWATextension}{DW\_AT\_extension}(reference to 20\$)
1208                 \livelink{chap:DWTAGimportedmodule}{DW\_TAG\_imported\_module}         ! (6) using directive
1209                     \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 40\$)
1210                 \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1211                     \livelink{chap:DWATname}{DW\_AT\_name}("k")
1212                     \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1213                     \livelink{chap:DWATlocation}{DW\_AT\_location} ...
1214                     ...
1215 60\$: \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1216         \livelink{chap:DWATspecification}{DW\_AT\_specification}(reference to 34\$)
1217         \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} ...
1218         \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc} ...
1219         ...
1220 \end{alltt}
1221 \end{dwflisting}
1222 \begin{center}
1223 Figure~\ref{fig:namespaceexampledwarfdescription}: Namespace example: DWARF description \textit{(concluded)}
1224 \end{center}
1225 \end{figure}
1226
1227 \section{Member Function Example}
1228 \label{app:memberfunctionexample}
1229
1230 Consider the member function example fragment in 
1231 Figure \refersec{fig:memberfunctionexamplesourcefragment}.
1232 The DWARF representation in 
1233 Figure \refersec{fig:memberfunctionexampledwarfdescription}
1234 is appropriate.
1235
1236 \begin{figure}[Here]
1237 \begin{lstlisting}
1238 class A
1239 {
1240     void func1(int x1);
1241     void func2() const;
1242     static void func3(int x3);
1243 };
1244 void A::func1(int x) {}
1245 \end{lstlisting}
1246 \caption{Member function example: source fragment}
1247 \label{fig:memberfunctionexamplesourcefragment}
1248 \end{figure}
1249
1250 \begin{figure}[h]
1251 \figurepart{1}{2}
1252 \begin{dwflisting}
1253 \begin{alltt}
1254 1\$: \livelink{chap:DWTAGunspecifiedtype}{DW\_TAG\_unspecified\_type}
1255         \livelink{chap:DWATname}{DW\_AT\_name}("void")
1256                 ...
1257 2\$: \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
1258         \livelink{chap:DWATname}{DW\_AT\_name}("int")
1259         ...
1260 3\$: \livelink{chap:DWTAGclasstype}{DW\_TAG\_class\_type}
1261         \livelink{chap:DWATname}{DW\_AT\_name}("A")
1262         ...
1263 4\$:    \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type}
1264             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 3\$)
1265             ...
1266 5\$:    \livelink{chap:DWTAGconsttype}{DW\_TAG\_const\_type}
1267             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 3\$)
1268             ...
1269 6\$:    \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type}
1270             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 5\$)
1271             ...
1272
1273 7\$:    \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1274             \livelink{chap:DWATdeclaration}{DW\_AT\_declaration}
1275             \livelink{chap:DWATname}{DW\_AT\_name}("func1")
1276             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1277             \livelink{chap:DWATobjectpointer}{DW\_AT\_object\_pointer}(reference to 8\$) \addtoindexx{object pointer attribute}
1278                 ! References a formal parameter in this 
1279                 ! member function
1280             ...
1281 \end{alltt}
1282 \end{dwflisting}
1283 \caption{Member function example: DWARF description}
1284 \label{fig:memberfunctionexampledwarfdescription}
1285 \end{figure}
1286
1287 \begin{figure}[p]
1288 \figurepart{2}{2}
1289 \begin{dwflisting}
1290 \begin{alltt}
1291 8\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1292                 \livelink{chap:DWATartificial}{DW\_AT\_artificial}(true)
1293                 \livelink{chap:DWATname}{DW\_AT\_name}("this")
1294                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 4\$)
1295                     ! Makes type of 'this' as 'A*' =>
1296                     ! func1 has not been marked const 
1297                     ! or volatile
1298                 \livelink{chap:DWATlocation}{DW\_AT\_location} ...
1299                 ...
1300 9\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1301                 \livelink{chap:DWATname}{DW\_AT\_name}(x1)
1302                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 2\$)
1303                 ...
1304 10\$:    \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1305              \livelink{chap:DWATdeclaration}{DW\_AT\_declaration}
1306              \livelink{chap:DWATname}{DW\_AT\_name}("func2")
1307              \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1308              \livelink{chap:DWATobjectpointer}{DW\_AT\_object\_pointer}(reference to 11\$) \addtoindexx{object pointer attribute}
1309              ! References a formal parameter in this 
1310              ! member function
1311              ...
1312 11\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1313                  \livelink{chap:DWATartificial}{DW\_AT\_artificial}(true)
1314                  \livelink{chap:DWATname}{DW\_AT\_name}("this")
1315                  \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 6\$)
1316                  ! Makes type of 'this' as 'A const*' =>
1317                  !     func2 marked as const
1318                  \livelink{chap:DWATlocation}{DW\_AT\_location} ...
1319                  ...
1320 12\$:    \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1321              \livelink{chap:DWATdeclaration}{DW\_AT\_declaration}
1322              \livelink{chap:DWATname}{DW\_AT\_name}("func3")
1323              \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1324              ...
1325                  ! No object pointer reference formal parameter
1326                  ! implies func3 is static
1327 13\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1328                  \livelink{chap:DWATname}{DW\_AT\_name}(x3)
1329                  \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 2\$)
1330                  ...
1331 \end{alltt}
1332 \end{dwflisting}
1333 \begin{center}
1334 Figure~\ref{fig:memberfunctionexampledwarfdescription}: Member function example: DWARF description \textit{(concluded)}
1335 \end{center}
1336 \end{figure}
1337
1338 \clearpage
1339 \section{Line Number Program Example}
1340 \label{app:linenumberprogramexample}
1341
1342 Consider the simple source file and the resulting machine
1343 code for the Intel 8086 processor in 
1344 Figure \refersec{fig:linenumberprogramexamplemachinecode}.
1345
1346 \begin{figure}[here]
1347 \begin{lstlisting}
1348 1: int
1349 2: main()
1350     0x239: push pb
1351     0x23a: mov bp,sp
1352 3: {
1353 4: printf("Omit needless words\n");
1354     0x23c: mov ax,0xaa
1355     0x23f: push ax
1356     0x240: call _printf
1357     0x243: pop cx
1358 5: exit(0);
1359     0x244: xor ax,ax
1360     0x246: push ax
1361     0x247: call _exit
1362     0x24a: pop cx
1363 6: }
1364     0x24b: pop bp
1365     0x24c: ret
1366 7: 0x24d:
1367 \end{lstlisting}
1368 \caption{Line number program example: machine code}
1369 \label{fig:linenumberprogramexamplemachinecode}
1370 \end{figure}
1371
1372 Suppose the line number program header includes the following
1373 (header fields not needed 
1374 \addtoindexx{line\_base}
1375 below 
1376 \addtoindexx{line\_range}
1377 are 
1378 \addtoindexx{opcode\_base}
1379 not 
1380 \addtoindexx{minumum\_instruction\_length}
1381 shown):
1382 \begin{alltt}
1383     version                       4
1384     minimum_instruction_length    1
1385     opcode_base                  10   ! Opcodes 10-12 not needed
1386     line_base                     1
1387     line_range                   15
1388 \end{alltt}
1389
1390
1391 Table \refersec{tab:linenumberprogramexampleoneencoding}
1392 shows one encoding of the line number program, which occupies
1393 12 bytes (the opcode SPECIAL(\textit{m},\textit{n}) indicates the special opcode
1394 generated for a line increment of \textit{m} and an address increment
1395 of \textit{n}).
1396
1397 \newpage
1398 \begin{centering}
1399 \setlength{\extrarowheight}{0.1cm}
1400 \begin{longtable}{l|l|l}
1401   \caption{Line number program example: one \mbox{encoding}}
1402   \label{tab:linenumberprogramexampleoneencoding} \\
1403   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
1404 \endfirsthead
1405   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
1406 \endhead
1407   \hline \emph{Continued on next page}
1408 \endfoot
1409   \hline
1410 \endlastfoot
1411 \livelink{chap:DWLNSadvancepc}{DW\_LNS\_advance\_pc}&LEB128(0x239)&0x2, 0xb9, 0x04 \\
1412 SPECIAL(2, 0)& &0xb  \\
1413 SPECIAL(2, 3)& &0x38 \\
1414 SPECIAL(1, 8)& &0x82 \\
1415 SPECIAL(1, 7)& &0x73 \\
1416 \livelink{chap:DWLNSadvancepc}{DW\_LNS\_advance\_pc}&LEB128(2)&0x2, 0x2 \\
1417 \livelink{chap:DWLNEendsequence}{DW\_LNE\_end\_sequence} &&0x0, 0x1, 0x1 \\
1418 \end{longtable}
1419 \end{centering}
1420
1421
1422 Table \refersec{tab:linenumberprogramexamplealternateencoding}
1423 shows an alternate 
1424 encoding of the same program using 
1425 standard opcodes to advance
1426 the program counter; 
1427 this encoding occupies 22 bytes.
1428
1429 \begin{centering}
1430 \setlength{\extrarowheight}{0.1cm}
1431 \begin{longtable}{l|l|l}
1432   \caption{Line number program example: alternate encoding} 
1433   \label{tab:linenumberprogramexamplealternateencoding} \\
1434   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
1435 \endfirsthead
1436   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
1437 \endhead
1438   \hline \emph{Continued on next page}
1439 \endfoot
1440   \hline
1441 \endlastfoot
1442 \livelink{chap:DWLNSfixedadvancepc}{DW\_LNS\_fixed\_advance\_pc}&0x239&0x9, 0x39, 0x2        \\
1443 SPECIAL(2, 0)&& 0xb        \\
1444 \livelink{chap:DWLNSfixedadvancepc}{DW\_LNS\_fixed\_advance\_pc}&0x3&0x9, 0x3, 0x0        \\
1445 SPECIAL(2, 0)&&0xb        \\
1446 \livelink{chap:DWLNSfixedadvancepc}{DW\_LNS\_fixed\_advance\_pc}&0x8&0x9, 0x8, 0x0        \\
1447 SPECIAL(1, 0)&& 0xa        \\
1448 \livelink{chap:DWLNSfixedadvancepc}{DW\_LNS\_fixed\_advance\_pc}&0x7&0x9, 0x7, 0x0        \\
1449 SPECIAL(1, 0) && 0xa        \\
1450 \livelink{chap:DWLNSfixedadvancepc}{DW\_LNS\_fixed\_advance\_pc}&0x2&0x9, 0x2, 0x0        \\
1451 \livelink{chap:DWLNEendsequence}{DW\_LNE\_end\_sequence}&&0x0, 0x1, 0x1        \\
1452 \end{longtable}
1453 \end{centering}
1454
1455
1456 \section{Call Frame Information Example}
1457 \label{app:callframeinformationexample}
1458
1459 The following example uses a hypothetical RISC machine in
1460 the style of the Motorola 88000.
1461 \begin{itemize}
1462 \item Memory is byte addressed.
1463
1464 \item Instructions are all 4 bytes each and word aligned.
1465
1466 \item Instruction operands are typically of the form:
1467 \begin{alltt}
1468     <destination.reg>, <source.reg>, <constant>
1469 \end{alltt}
1470
1471 \item The address for the load and store instructions is computed
1472 by adding the contents of the
1473 source register with the constant.
1474
1475 \item There are eight 4\dash byte registers:
1476 \newline
1477 \begin{tabular}{p{5mm}l}
1478    & R0 always 0 \\
1479    & R1 holds return address on call \\
1480    & R2-R3 temp registers (not preserved on call) \\
1481    & R4-R6 preserved on call \\
1482    & R7 stack pointer \\
1483 \end{tabular}
1484
1485 \item  The stack grows in the negative direction.
1486
1487 \item The architectural ABI committee specifies that the
1488 stack pointer (R7) is the same as the CFA
1489
1490 \end{itemize}
1491
1492 Figure \referfol{fig:callframeinformationexamplemachinecodefragments}
1493 shows two code fragments from a subroutine called
1494 foo that uses a frame pointer (in addition to the stack
1495 pointer). The first column values are byte addresses. 
1496 % The \space is so we get a space after >
1497 \textless fs\textgreater\ denotes the stack frame size in bytes, namely 12.
1498
1499
1500 \begin{figure}[here]
1501 \begin{lstlisting}
1502        ;; start prologue
1503 foo    sub   R7, R7, <fs>        ; Allocate frame
1504 foo+4  store R1, R7, (<fs>-4)    ; Save the return address
1505 foo+8  store R6, R7, (<fs>-8)    ; Save R6
1506 foo+12 add   R6, R7, 0           ; R6 is now the Frame ptr
1507 foo+16 store R4, R6, (<fs>-12)   ; Save a preserved reg
1508        ;; This subroutine does not change R5
1509        ...
1510        ;; Start epilogue (R7 is returned to entry value)
1511 foo+64 load  R4, R6, (<fs>-12)   ; Restore R4
1512 foo+68 load  R6, R7, (<fs>-8)    ; Restore R6
1513 foo+72 load  R1, R7, (<fs>-4)    ; Restore return address
1514 foo+76 add   R7, R7, <fs>        ; Deallocate frame
1515 foo+80 jump  R1                  ; Return
1516 foo+84
1517 \end{lstlisting}
1518 \caption{Call frame information example: machine code fragments}
1519 \label{fig:callframeinformationexamplemachinecodefragments}
1520 \end{figure}
1521
1522
1523 An abstract table 
1524 (see Section \refersec{chap:structureofcallframeinformation}) 
1525 for the foo subroutine is shown in 
1526 Table \referfol{tab:callframeinformationexampleconceptualmatrix}.
1527 Corresponding fragments from the
1528 \dotdebugframe{} section are shown in 
1529 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
1530
1531 The following notations apply in 
1532 Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
1533 \newline
1534 \begin{tabular}{p{5mm}l}
1535 &1.  R8 is the return address \\
1536 &2.  s = same\_value rule \\
1537 &3.  u = undefined rule \\
1538 &4.  rN = register(N) rule \\
1539 &5.  cN = offset(N) rule \\
1540 &6.  a = architectural rule \\
1541 \end{tabular}
1542
1543 \begin{centering}
1544 \setlength{\extrarowheight}{0.1cm}
1545 \begin{longtable}{l|llllllllll}
1546   \caption{Call frame information example: conceptual matrix} 
1547   \label{tab:callframeinformationexampleconceptualmatrix} \\
1548   \hline \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
1549 \endfirsthead
1550   \bfseries Location &\bfseries CFA &\bfseries R0 & \bfseries R1 & \bfseries R2 &\bfseries R3 &\bfseries R4 &\bfseries R5 &\bfseries R6 &\bfseries R7 &\bfseries R8\\ \hline
1551 \endhead
1552   \hline \emph{Continued on next page}
1553 \endfoot
1554   \hline
1555 \endlastfoot
1556 foo&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
1557 foo+4&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
1558 foo+8&[R7]+fs&s&u&u&u&s&s&s&a&c-4 \\
1559 foo+12&[R7]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
1560 foo+16&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
1561 foo+20&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
1562 ...&&&&&&&&&& \\
1563 foo+64&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
1564 foo+68&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4  \\
1565 foo+72&[R7]+fs&s&u&u&u&s&s&s&a&c-4  \\
1566 foo+76&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
1567 foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
1568 \end{longtable}
1569 \end{centering}
1570
1571 \clearpage      % ?????
1572
1573 \begin{centering}
1574 \setlength{\extrarowheight}{0.1cm}
1575 \begin{longtable}{l|ll}
1576   \caption{Call frame information example: common information entry encoding} 
1577   \label{tab:callframeinformationexamplecommoninformationentryencoding} 
1578   \\
1579   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1580 \endfirsthead
1581   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1582 \endhead
1583   \hline \emph{Continued on next page}
1584 \endfoot
1585   \hline
1586 \endlastfoot
1587 cie&36&length    \\
1588 cie+4&\xffffffff&CIE\_id    \\
1589 cie+8&4&version    \\
1590 cie+9&0&augmentation     \\
1591 cie+10&4&address size    \\
1592 cie+11&0&segment size    \\
1593 cie+12&4&code\_alignment\_factor, \textless caf \textgreater    \\
1594 cie+13&-4&data\_alignment\_factor, \textless daf \textgreater    \\
1595 cie+14&8&R8 is the return addr.    \\
1596 cie+15&\livelink{chap:DWCFAdefcfa}{DW\_CFA\_def\_cfa} (7, 0)&CFA = [R7]+0    \\
1597 cie+18&\livelink{chap:DWCFAsamevalue}{DW\_CFA\_same\_value} (0)&R0 not modified (=0)    \\
1598 cie+20&\livelink{chap:DWCFAundefined}{DW\_CFA\_undefined} (1)&R1 scratch    \\
1599 cie+22&\livelink{chap:DWCFAundefined}{DW\_CFA\_undefined} (2)&R2 scratch    \\
1600 cie+24&\livelink{chap:DWCFAundefined}{DW\_CFA\_undefined} (3)&R3 scratch    \\
1601 cie+26&\livelink{chap:DWCFAsamevalue}{DW\_CFA\_same\_value} (4)&R4 preserve    \\
1602 cie+28&\livelink{chap:DWCFAsamevalue}{DW\_CFA\_same\_value} (5)&R5 preserve    \\
1603 cie+30&\livelink{chap:DWCFAsamevalue}{DW\_CFA\_same\_value} (6)&R6 preserve    \\
1604 cie+32&\livelink{chap:DWCFAsamevalue}{DW\_CFA\_same\_value} (7)&R7 preserve    \\
1605 cie+34&\livelink{chap:DWCFAregister}{DW\_CFA\_register} (8, 1)&R8 is in R1    \\
1606 cie+37&\livelink{chap:DWCFAnop}{DW\_CFA\_nop} &padding    \\
1607 cie+38&\livelink{chap:DWCFAnop}{DW\_CFA\_nop} &padding \\
1608 cie+39& \livelink{chap:DWCFAnop}{DW\_CFA\_nop}&padding  \\
1609 cie+40 &&  \\
1610 \end{longtable}
1611 \end{centering}
1612
1613
1614 The following notations apply in 
1615 Table \refersec{tab:callframeinformationexampleframedescriptionentryencoding}:
1616 \newline
1617 \begin{tabular}{p{5mm}l}
1618 &\texttt{<fs>  =} frame size \\
1619 &\texttt{<caf> =} code alignment factor \\
1620 &\texttt{<daf> =} data alignment factor \\
1621 \end{tabular}
1622
1623
1624 \begin{centering}
1625 \setlength{\extrarowheight}{0.1cm}
1626 \begin{longtable}{l|ll}
1627   \caption{Call frame information example: frame description entry encoding} 
1628   \label{tab:callframeinformationexampleframedescriptionentryencoding} \\
1629   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1630 \endfirsthead
1631   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1632 \endhead
1633   \hline \emph{Continued on next page}
1634 \endfoot
1635   \hline
1636 \endlastfoot
1637 fde&40&length \\
1638 fde+4&cie&CIE\_ptr \\
1639 fde+8&foo&initial\_location \\
1640 fde+12&84&address\_range \\
1641 fde+16&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1)&instructions \\
1642 fde+17&\livelink{chap:DWCFAdefcfaoffset}{DW\_CFA\_def\_cfa\_offset}(12)& \textless fs\textgreater \\
1643 fde+19&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1)&4/\textless caf\textgreater \\
1644 fde+20&\livelink{chap:DWCFAoffset}{DW\_CFA\_offset}(8,1)&-4/\textless daf\textgreater (2nd parameter) \\
1645 fde+22&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1)& \\
1646 fde+23&\livelink{chap:DWCFAoffset}{DW\_CFA\_offset}(6,2)&-8/\textless daf\textgreater (2nd parameter)  \\
1647 fde+25&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1) & \\
1648 fde+26&\livelink{chap:DWCFAdefcfaregister}{DW\_CFA\_def\_cfa\_register}(6) & \\
1649 fde+28&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1) & \\
1650 fde+29&\livelink{chap:DWCFAoffset}{DW\_CFA\_offset}(4,3)&-12/\textless daf\textgreater (2nd parameter) \\
1651 fde+31&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(12)&44/\textless caf\textgreater \\
1652 fde+32&\livelink{chap:DWCFArestore}{DW\_CFA\_restore}(4)& \\
1653 fde+33&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1) & \\
1654 fde+34&\livelink{chap:DWCFArestore}{DW\_CFA\_restore}(6) & \\
1655 fde+35&\livelink{chap:DWCFAdefcfaregister}{DW\_CFA\_def\_cfa\_register}(7)  & \\
1656 fde+37&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1) & \\
1657 fde+38&\livelink{chap:DWCFArestore}{DW\_CFA\_restore}(8) &\\
1658 fde+39&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1) &\\
1659 fde+40&\livelink{chap:DWCFAdefcfaoffset}{DW\_CFA\_def\_cfa\_offset}(0)  &\\
1660 fde+42&\livelink{chap:DWCFAnop}{DW\_CFA\_nop}&padding \\
1661 fde+43&\livelink{chap:DWCFAnop}{DW\_CFA\_nop}&padding \\
1662 fde+44 && \\
1663 \end{longtable}
1664 \end{centering}
1665
1666 \section{Inlining Examples}
1667 \label{app:inliningexamples}
1668 The pseudo\dash source in 
1669 Figure \referfol{fig:inliningexamplespseudosourcefragment}
1670 is used to illustrate the
1671 \addtoindexx{inlined subprogram call!examples}
1672 use of DWARF to describe inlined subroutine calls. This
1673 example involves a nested subprogram \texttt{INNER} that makes uplevel
1674 references to the formal parameter and local variable of the
1675 containing subprogram \texttt{OUTER}.
1676
1677 \begin{figure}[here]
1678 \begin{lstlisting}
1679 inline procedure OUTER (OUTER_FORMAL : integer) =
1680     begin
1681     OUTER_LOCAL : integer;
1682     procedure INNER (INNER_FORMAL : integer) =
1683         begin
1684         INNER_LOCAL : integer;
1685         print(INNER_FORMAL + OUTER_LOCAL);
1686         end;
1687     INNER(OUTER_LOCAL);
1688     ...
1689     INNER(31);
1690     end;
1691 ! Call OUTER
1692 !
1693 OUTER(7);
1694 \end{lstlisting}
1695 \caption{Inlining examples: pseudo-source fragmment} 
1696 \label{fig:inliningexamplespseudosourcefragment}
1697 \end{figure}
1698
1699
1700 There are several approaches that a compiler might take to
1701 inlining for this sort of example. This presentation considers
1702 three such approaches, all of which involve inline expansion
1703 of subprogram \texttt{OUTER}. (If \texttt{OUTER} is not inlined, the inlining
1704 reduces to a simpler single level subset of the two level
1705 approaches considered here.)
1706
1707 The approaches are:
1708 \begin{enumerate}[1. ]
1709 \item  Inline both \texttt{OUTER} and \texttt{INNER} in all cases
1710
1711 \item Inline \texttt{OUTER}, multiple \texttt{INNER}s \\
1712 Treat \texttt{INNER} as a non\dash inlinable part of \texttt{OUTER}, compile and
1713 call a distinct normal version of \texttt{INNER} defined within each
1714 inlining of \texttt{OUTER}.
1715
1716 \item Inline \texttt{OUTER}, one \texttt{INNER} \\
1717 Compile \texttt{INNER} as a single normal subprogram which is called
1718 from every inlining of \texttt{OUTER}.
1719 \end{enumerate}
1720
1721 This discussion does not consider why a compiler might choose
1722 one of these approaches; it considers only how to describe
1723 the result.
1724
1725 In the examples that follow in this section, the debugging
1726 information entries are given mnemonic labels of the following
1727 form
1728 \begin{verbatim}
1729     <io>.<ac>.<n>.<s>
1730 \end{verbatim}
1731 where
1732 \begin{description}
1733 \item[\textless io\textgreater]
1734 is either \texttt{INNER} or \texttt{OUTER} to indicate to which
1735 subprogram the debugging information entry applies, 
1736 \item[\textless ac\textgreater]
1737 is either AI or CI to indicate \doublequote{abstract instance} or
1738 \doublequote{concrete instance} respectively, 
1739 \item[\textless n\textgreater]
1740 is the number of the
1741 alternative being considered, and 
1742 \item[\textless s\textgreater]
1743 is a sequence number that
1744 distinguishes the individual entries. 
1745 \end{description}
1746 There is no implication
1747 that symbolic labels, nor any particular naming convention,
1748 are required in actual use.
1749
1750 For conciseness, declaration coordinates and call coordinates are omitted.
1751
1752 \subsection{Alternative \#1: inline both OUTER and INNER}
1753 \label{app:inlinebothouterandinner}
1754
1755 A suitable abstract instance for an alternative where both
1756 \texttt{OUTER} and \texttt{INNER} are always inlined is shown in 
1757 Figure \refersec{fig:inliningexample1abstractinstance}.
1758
1759 Notice in 
1760 Figure \ref{fig:inliningexample1abstractinstance} 
1761 that the debugging information entry for
1762 \texttt{INNER} (labelled \texttt{INNER.AI.1.1}) is nested in (is a child of)
1763 that for \texttt{OUTER} (labelled \texttt{OUTER.AI.1.1}). Nonetheless, the
1764 abstract instance tree for \texttt{INNER} is considered to be separate
1765 and distinct from that for \texttt{OUTER}.
1766
1767 The call of \texttt{OUTER} shown in 
1768 Figure \refersec{fig:inliningexamplespseudosourcefragment}
1769 might be described as
1770 shown in 
1771 Figure \refersec{fig:inliningexample1concreteinstance}.
1772
1773
1774 \begin{figure}[p]
1775 \begin{dwflisting}
1776 \begin{alltt}
1777     ! Abstract instance for OUTER
1778     ! \addtoindexx{abstract instance!example}
1779 OUTER.AI.1.1:
1780     \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1781         \livelink{chap:DWATname}{DW\_AT\_name}("OUTER")
1782         \livelink{chap:DWATinline}{DW\_AT\_inline}(\livelink{chap:DWINLdeclaredinlined}{DW\_INL\_declared\_inlined})
1783         ! No low/high PCs
1784 OUTER.AI.1.2:
1785         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1786             \livelink{chap:DWATname}{DW\_AT\_name}("OUTER\_FORMAL")
1787             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1788             ! No location
1789 OUTER.AI.1.3:
1790         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1791             \livelink{chap:DWATname}{DW\_AT\_name}("OUTER\_LOCAL")
1792             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1793             ! No location
1794         !
1795         ! Abstract instance for INNER
1796         !
1797 INNER.AI.1.1:
1798         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1799             \livelink{chap:DWATname}{DW\_AT\_name}("INNER")
1800             \livelink{chap:DWATinline}{DW\_AT\_inline}(\livelink{chap:DWINLdeclaredinlined}{DW\_INL\_declared\_inlined})
1801             ! No low/high PCs
1802 INNER.AI.1.2:
1803             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1804                 \livelink{chap:DWATname}{DW\_AT\_name}("INNER\_FORMAL")
1805                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1806                 ! No location
1807 INNER.AI.1.3:
1808             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1809                 \livelink{chap:DWATname}{DW\_AT\_name}("INNER\_LOCAL")
1810                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1811                 ! No location
1812             ...
1813             0
1814         ! No \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine} (concrete instance)
1815         ! for INNER corresponding to calls of INNER
1816         ...
1817         0
1818 \end{alltt}
1819 \end{dwflisting}
1820 \caption{Inlining example \#1: abstract instance}
1821 \label{fig:inliningexample1abstractinstance}
1822 \end{figure}
1823
1824 \begin{figure}[p]
1825 \begin{dwflisting}
1826 \begin{alltt}
1827 ! Concrete instance for call "OUTER(7)"
1828 ! \addtoindexx{concrete instance!example}
1829 OUTER.CI.1.1:
1830     \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
1831         ! No name
1832         \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.1.1)
1833         \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}(...)
1834         \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}(...)
1835 OUTER.CI.1.2:
1836         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1837             ! No name
1838             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.1.2)
1839             \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}(7)
1840 OUTER.CI.1.3:
1841         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1842             ! No name
1843             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.1.3)
1844             \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
1845         !
1846         ! No \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram} (abstract instance) for INNER
1847         !
1848         ! Concrete instance for call INNER(OUTER\_LOCAL)
1849         !
1850 INNER.CI.1.1:
1851         \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
1852             ! No name
1853             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to INNER.AI.1.1)
1854             \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}(...)
1855             \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}(...)
1856             \livelink{chap:DWATstaticlink}{DW\_AT\_static\_link}(...)
1857 INNER.CI.1.2:
1858             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1859                 ! No name
1860                 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to INNER.AI.1.2)
1861                 \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
1862 INNER.CI.1.3:
1863             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1864                 ! No name
1865                 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to INNER.AI.1.3)
1866                 \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
1867             ...
1868             0
1869         ! Another concrete instance of INNER within OUTER
1870         ! for the call "INNER(31)"
1871         ...
1872         0
1873 \end{alltt}
1874 \end{dwflisting}
1875 \caption{Inlining example \#1: concrete instance}
1876 \label{fig:inliningexample1concreteinstance}
1877 \end{figure}
1878
1879 \subsection{Alternative \#2: Inline OUTER, multiple INNERs}
1880 \label{app:inlineoutermultiipleinners}
1881
1882
1883 In the second alternative we assume that subprogram \texttt{INNER}
1884 is not inlinable for some reason, but subprogram \texttt{OUTER} is
1885 inlinable. 
1886 \addtoindexx{concrete instance!example}
1887 Each concrete inlined instance of \texttt{OUTER} has its
1888 own normal instance of \texttt{INNER}. 
1889 The abstract instance for \texttt{OUTER},
1890 \addtoindexx{abstract instance!example}
1891 which includes \texttt{INNER}, is shown in 
1892 Figure \refersec{fig:inliningexample2abstractinstance}.
1893
1894 Note that the debugging information in 
1895 Figure \ref{fig:inliningexample2abstractinstance}
1896 differs from that in 
1897 Figure \refersec{fig:inliningexample1abstractinstance}
1898 in that \texttt{INNER} lacks a 
1899 \livelink{chap:DWATinline}{DW\_AT\_inline} attribute
1900 and therefore is not a distinct abstract instance. \texttt{INNER}
1901 is merely an out\dash of\dash line routine that is part of \texttt{OUTER}\textquoteright s
1902 abstract instance. This is reflected in the Figure by
1903 \addtoindexx{abstract instance!example}
1904 the fact that the labels for \texttt{INNER} use the substring \texttt{OUTER}
1905 instead of \texttt{INNER}.
1906
1907 A resulting 
1908 \addtoindexx{concrete instance!example}
1909 concrete inlined instance of \texttt{OUTER} is shown in
1910 Figure \refersec{fig:inliningexample2concreteinstance}.
1911
1912 Notice in 
1913 Figure \ref{fig:inliningexample2concreteinstance}
1914 that \texttt{OUTER} is expanded as a concrete
1915 \addtoindexx{concrete instance!example}
1916 inlined instance, and that \texttt{INNER} is nested within it as a
1917 concrete out\dash of\dash line subprogram. Because \texttt{INNER} is cloned
1918 for each inline expansion of \texttt{OUTER}, only the invariant
1919 attributes of \texttt{INNER} 
1920 (for example, \livelink{chap:DWATname}{DW\_AT\_name}) are specified
1921 in the abstract instance of \texttt{OUTER}, and the low\dash level,
1922 \addtoindexx{abstract instance!example}
1923 instance\dash specific attributes of \texttt{INNER} (for example,
1924 \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}) are specified in 
1925 each concrete instance of \texttt{OUTER}.
1926 \addtoindexx{concrete instance!example}
1927
1928 The several calls of \texttt{INNER} within \texttt{OUTER} are compiled as normal
1929 calls to the instance of \texttt{INNER} that is specific to the same
1930 instance of \texttt{OUTER} that contains the calls.
1931
1932 \begin{figure}[t]
1933 \begin{dwflisting}
1934 \begin{alltt}
1935     ! Abstract instance for OUTER
1936     ! \addtoindex{abstract instance}
1937 OUTER.AI.2.1:
1938     \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1939         \livelink{chap:DWATname}{DW\_AT\_name}("OUTER")
1940         \livelink{chap:DWATinline}{DW\_AT\_inline}(\livelink{chap:DWINLdeclaredinlined}{DW\_INL\_declared\_inlined})
1941         ! No low/high PCs
1942 OUTER.AI.2.2:
1943         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1944             \livelink{chap:DWATname}{DW\_AT\_name}("OUTER\_FORMAL")
1945             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1946             ! No location
1947 OUTER.AI.2.3:
1948         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1949             \livelink{chap:DWATname}{DW\_AT\_name}("OUTER\_LOCAL")
1950             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1951             ! No location
1952         !
1953         ! Nested out-of-line INNER subprogram
1954         !
1955 OUTER.AI.2.4:
1956         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1957             \livelink{chap:DWATname}{DW\_AT\_name}("INNER")
1958             ! No \livelink{chap:DWATinline}{DW\_AT\_inline}
1959             ! No low/high PCs, frame\_base, etc.
1960 OUTER.AI.2.5:
1961             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1962                 \livelink{chap:DWATname}{DW\_AT\_name}("INNER\_FORMAL")
1963                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1964                 ! No location
1965 OUTER.AI.2.6:
1966             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1967                 \livelink{chap:DWATname}{DW\_AT\_name}("INNER\_LOCAL")
1968                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1969                 ! No location
1970             ...
1971             0
1972         ...
1973         0
1974 \end{alltt}
1975 \end{dwflisting}
1976 \caption{Inlining example \#2: abstract instance}
1977 \label{fig:inliningexample2abstractinstance}
1978 \end{figure}
1979
1980 \begin{figure}[t]
1981 \begin{dwflisting}
1982 \begin{alltt}
1983
1984     ! Concrete instance for call "OUTER(7)"
1985     !
1986 OUTER.CI.2.1:
1987     \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
1988         ! No name
1989         \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.2.1)
1990         \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}(...)
1991         \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}(...)
1992 OUTER.CI.2.2:
1993         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1994             ! No name
1995             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.2.2)
1996             \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
1997 OUTER.CI.2.3:
1998         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1999             ! No name
2000             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.2.3)
2001             \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2002         !
2003         ! Nested out-of-line INNER subprogram
2004         !
2005 OUTER.CI.2.4:
2006         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
2007             ! No name
2008             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.2.4)
2009             \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}(...)
2010             \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}(...)
2011             \livelink{chap:DWATframebase}{DW\_AT\_frame\_base}(...)
2012             \livelink{chap:DWATstaticlink}{DW\_AT\_static\_link}(...)
2013 OUTER.CI.2.5:
2014             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2015                 ! No name
2016                 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.2.5)
2017                 \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2018 OUTER.CI.2.6:
2019             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2020                 ! No name
2021                 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AT.2.6)
2022                 \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2023             ...
2024             0
2025         ...
2026         0
2027 \end{alltt}
2028 \end{dwflisting}
2029 \caption{Inlining example \#2: concrete instance}
2030 \label{fig:inliningexample2concreteinstance}
2031 \end{figure}
2032
2033 \subsection{Alternative \#3: inline OUTER, one normal INNER}
2034 \label{app:inlineouteronenormalinner}
2035
2036 In the third approach, one normal subprogram for \texttt{INNER} is
2037 compiled which is called from all concrete inlined instances of
2038 \addtoindexx{concrete instance!example}
2039 \addtoindexx{abstract instance!example}
2040 \texttt{OUTER}. The abstract instance for \texttt{OUTER} is shown in 
2041 Figure \refersec{fig:inliningexample3abstractinstance}.
2042
2043 The most distinctive aspect of that Figure is that subprogram
2044 \texttt{INNER} exists only within the abstract instance of \texttt{OUTER},
2045 and not in \texttt{OUTER}\textquoteright s concrete instance. In the abstract
2046 \addtoindexx{concrete instance!example}
2047 \addtoindexx{abstract instance!example}
2048 instance of \texttt{OUTER}, the description of \texttt{INNER} has the full
2049 complement of attributes that would be expected for a
2050 normal subprogram. 
2051 While attributes such as 
2052 \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc},
2053 \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}, 
2054 \livelink{chap:DWATlocation}{DW\_AT\_location},
2055 and so on, typically are omitted
2056 \addtoindexx{high PC attribute}
2057 from 
2058 \addtoindexx{low PC attribute}
2059 an 
2060 \addtoindexx{location attribute}
2061 abstract instance because they are not invariant across
2062 instances of the containing abstract instance, in this case
2063 those same attributes are included precisely because they are
2064 invariant -- there is only one subprogram \texttt{INNER} to be described
2065 and every description is the same.
2066
2067 A concrete inlined instance of \texttt{OUTER} is illustrated in
2068 Figure \refersec{fig:inliningexample3concreteinstance}.
2069
2070 Notice in 
2071 Figure \ref{fig:inliningexample3concreteinstance}
2072 that there is no DWARF representation for
2073 \texttt{INNER} at all; the representation of \texttt{INNER} does not vary across
2074 instances of \texttt{OUTER} and the abstract instance of \texttt{OUTER} includes
2075 the complete description of \texttt{INNER}, so that the description of
2076 \texttt{INNER} may be (and for reasons of space efficiency, should be)
2077 omitted from each 
2078 \addtoindexx{concrete instance!example}
2079 concrete instance of \texttt{OUTER}.
2080
2081 There is one aspect of this approach that is problematical from
2082 the DWARF perspective. The single compiled instance of \texttt{INNER}
2083 is assumed to access up\dash level variables of \texttt{OUTER}; however,
2084 those variables may well occur at varying positions within
2085 the frames that contain the 
2086 \addtoindexx{concrete instance!example}
2087 concrete inlined instances. A
2088 compiler might implement this in several ways, including the
2089 use of additional compiler-generated parameters that provide
2090 reference parameters for the up\dash level variables, or a 
2091 compiler-generated static link like parameter that points to the group
2092 of up\dash level entities, among other possibilities. In either of
2093 these cases, the DWARF description for the location attribute
2094 of each uplevel variable needs to be different if accessed
2095 from within \texttt{INNER} compared to when accessed from within the
2096 instances of \texttt{OUTER}. An implementation is likely to require
2097 vendor\dash specific DWARF attributes and/or debugging information
2098 entries to describe such cases.
2099
2100 Note that in C++, a member function of a class defined within
2101 a function definition does not require any vendor\dash specific
2102 extensions because the C++ language disallows access to
2103 entities that would give rise to this problem. (Neither \texttt{extern}
2104 variables nor \texttt{static} members require any form of static link
2105 for accessing purposes.)
2106
2107 \begin{figure}[t]
2108 \begin{dwflisting}
2109 \begin{alltt}
2110     ! Abstract instance for OUTER
2111     ! \addtoindexx{abstract instance!example}
2112 OUTER.AI.3.1:
2113     \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
2114         \livelink{chap:DWATname}{DW\_AT\_name}("OUTER")
2115         \livelink{chap:DWATinline}{DW\_AT\_inline}(\livelink{chap:DWINLdeclaredinlined}{DW\_INL\_declared\_inlined})
2116         ! No low/high PCs
2117 OUTER.AI.3.2:
2118         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2119             \livelink{chap:DWATname}{DW\_AT\_name}("OUTER\_FORMAL")
2120             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
2121             ! No location
2122 OUTER.AI.3.3:
2123         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2124             \livelink{chap:DWATname}{DW\_AT\_name}("OUTER\_LOCAL")
2125             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
2126             ! No location
2127         !
2128         ! Normal INNER
2129         !
2130 OUTER.AI.3.4:
2131         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
2132             \livelink{chap:DWATname}{DW\_AT\_name}("INNER")
2133             \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}(...)
2134             \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}(...)
2135             \livelink{chap:DWATframebase}{DW\_AT\_frame\_base}(...)
2136             \livelink{chap:DWATstaticlink}{DW\_AT\_static\_link}(...)
2137 OUTER.AI.3.5:
2138             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2139                 \livelink{chap:DWATname}{DW\_AT\_name}("INNER\_FORMAL")
2140                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
2141                 \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2142 OUTER.AI.3.6:
2143             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2144                 \livelink{chap:DWATname}{DW\_AT\_name}("INNER\_LOCAL")
2145                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
2146                 \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2147             ...
2148             0
2149         ...
2150         0
2151 \end{alltt}
2152 \end{dwflisting}
2153 \caption{Inlining example \#3: abstract instance}
2154 \label{fig:inliningexample3abstractinstance}
2155 \end{figure}
2156
2157 \begin{figure}[t]
2158 \begin{dwflisting}
2159 \begin{alltt}
2160     ! Concrete instance for call "OUTER(7)"
2161     ! \addtoindexx{concrete instance!example}
2162 OUTER.CI.3.1:
2163     \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
2164         ! No name
2165         \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.3.1)
2166         \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}(...)
2167         \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}(...)
2168         \livelink{chap:DWATframebase}{DW\_AT\_frame\_base}(...)
2169 OUTER.CI.3.2:
2170         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2171             ! No name
2172             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.3.2)
2173             ! No type
2174             \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2175 OUTER.CI.3.3:
2176         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2177             ! No name
2178             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.3.3)
2179             ! No type
2180             \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2181         ! No \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram} for "INNER"
2182         ...
2183         0
2184 \end{alltt}
2185 \end{dwflisting}
2186 \caption{Inlining example \#3: concrete instance}
2187 \label{fig:inliningexample3concreteinstance}
2188 \end{figure}
2189
2190 \clearpage
2191 \section{Constant Expression Example}
2192 \label{app:constantexpressionexample}
2193 C++ generalizes the notion of constant expressions to include
2194 constant expression user-defined literals and functions.
2195 The constant declarations in Figure \refersec{fig:constantexpressionscsource}
2196 can be represented as illustrated in 
2197 Figure \refersec{fig:constantexpressionsdwarfdescription}.
2198
2199
2200 \begin{figure}[here]
2201 \begin{lstlisting}[numbers=none]
2202 constexpr double mass = 9.8;
2203 constexpr int square (int x) { return x * x; }
2204 float arr[square(9)]; // square() called and inlined
2205 \end{lstlisting}
2206 \caption{Constant expressions: C++ source} \label{fig:constantexpressionscsource}
2207 \end{figure}
2208
2209
2210 \begin{figure}[!h]
2211 \begin{dwflisting}
2212 \begin{alltt}
2213         ! For variable mass
2214         !
2215 1\$:     \livelink{chap:DWTAGconsttype}{DW\_TAG\_const\_type}
2216             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "double")
2217 2\$:     \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2218             \livelink{chap:DWATname}{DW\_AT\_name}("mass")
2219             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
2220             \livelink{chap:DWATconstexpr}{DW\_AT\_const\_expr}(true)
2221             \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}(9.8)
2222         ! Abstract instance for square
2223         !
2224 10\$:    \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
2225             \livelink{chap:DWATname}{DW\_AT\_name}("square")
2226             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2227             \livelink{chap:DWATinline}{DW\_AT\_inline}(\livelink{chap:DWINLinlined}{DW\_INL\_inlined})
2228 11\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2229                 \livelink{chap:DWATname}{DW\_AT\_name}("x")
2230                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2231         ! Concrete instance for square(9)
2232         ! \addtoindexx{concrete instance!example}
2233 20\$:    \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
2234             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to 10\$)
2235             \livelink{chap:DWATconstexpr}{DW\_AT\_const\_expr}(present)
2236             \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}(81)
2237             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2238                 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to 11\$)
2239                 \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}(9)
2240         ! Anonymous array type for arr
2241         !
2242 30\$:    \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type}
2243             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "float")
2244             \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}(324) ! 81*4
2245             \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
2246                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2247                 \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(reference to 20\$)
2248         ! Variable arr
2249         !
2250 40\$:    \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2251             \livelink{chap:DWATname}{DW\_AT\_name}("arr")
2252             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 30\$)
2253 \end{alltt}
2254 \end{dwflisting}
2255 \caption{Constant expressions: DWARF description}
2256 \label{fig:constantexpressionsdwarfdescription}
2257 \end{figure}
2258
2259 \section{Unicode Character Example}
2260 \label{app:unicodecharacterexample}
2261 \addtoindexx{Unicode|see {\textit{also} UTF-8}}
2262 The \addtoindex{Unicode} character encodings in
2263 Figure \refersec{fig:unicodecharacterexamplesource}
2264 can be described in DWARF as illustrated in 
2265 Figure \refersec{fig:unicodecharacterexampledwarfdescription}.
2266
2267 \begin{figure}[!h]
2268 \begin{lstlisting}[numbers=none]
2269 // C++ source
2270 //
2271 char16_t chr_a = u'h';
2272 char32_t chr_b = U'h';
2273 \end{lstlisting}
2274 \caption{Unicode character example: source}
2275 \label{fig:unicodecharacterexamplesource}
2276 \end{figure}
2277
2278 \begin{figure}[h]
2279 \begin{dwflisting}
2280 \begin{alltt}
2281
2282 ! DWARF description
2283 !
2284 1\$: \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
2285         \livelink{chap:DWATname}{DW\_AT\_name}("char16\_t")
2286         \livelink{chap:DWATencoding}{DW\_AT\_encoding}(\livelink{chap:DWATEUTF}{DW\_ATE\_UTF})
2287         \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}(2)
2288 2\$: \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
2289         \livelink{chap:DWATname}{DW\_AT\_name}("char32\_t")
2290         \livelink{chap:DWATencoding}{DW\_AT\_encoding}(\livelink{chap:DWATEUTF}{DW\_ATE\_UTF})
2291         \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}(4)
2292 3\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2293         \livelink{chap:DWATname}{DW\_AT\_name}("chr\_a")
2294         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
2295 4\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2296         \livelink{chap:DWATname}{DW\_AT\_name}("chr\_b")
2297         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 2\$)
2298 \end{alltt}
2299 \end{dwflisting}
2300 \caption{Unicode character example: DWARF description}
2301 \label{fig:unicodecharacterexampledwarfdescription}
2302 \end{figure}
2303
2304
2305 \section{Type-Safe Enumeration Example}
2306 \label{app:typesafeenumerationexample}
2307
2308 The \addtoindex{C++} type\dash safe enumerations in
2309 \addtoindexx{type-safe enumeration}
2310 Figure \refersec{fig:ctypesafeenumerationexamplesource}
2311 can be described in DWARF as illustrated in 
2312 Figure \refersec{fig:ctypesafeenumerationexampledwarf}.
2313
2314 \clearpage      % Get following source and DWARF on same page
2315
2316 \begin{figure}[H]
2317 \begin{lstlisting}[numbers=none]
2318 // C++ source
2319 //
2320 enum class E { E1, E2=100 };
2321 E e1;
2322 \end{lstlisting}
2323 \caption{Type-safe enumeration example: source}
2324 \label{fig:ctypesafeenumerationexamplesource}
2325 \end{figure}
2326
2327 \begin{figure}[H]
2328 \begin{dwflisting}
2329 \begin{alltt}
2330 ! DWARF description
2331 !
2332 11\$:  \livelink{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}
2333           \livelink{chap:DWATname}{DW\_AT\_name}("E")
2334           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2335           \livelink{chap:DWATenumclass}{DW\_AT\_enum\_class}(present)
2336 12\$:      \livelink{chap:DWTAGenumerator}{DW\_TAG\_enumerator}
2337               \livelink{chap:DWATname}{DW\_AT\_name}("E1")
2338               \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}(0)
2339 13\$:      \livelink{chap:DWTAGenumerator}{DW\_TAG\_enumerator}
2340               \livelink{chap:DWATname}{DW\_AT\_name}("E2")
2341               \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}(100)
2342 14\$:  \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2343          \livelink{chap:DWATname}{DW\_AT\_name}("e1")
2344          \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 11\$)
2345 \end{alltt}
2346 \end{dwflisting}
2347 \caption{Type-safe enumeration example: DWARF description}
2348 \label{fig:ctypesafeenumerationexampledwarf}
2349 \end{figure}
2350
2351
2352 \clearpage
2353 \section{Template Examples}
2354 \label{app:templateexample}
2355
2356 The C++ template example in
2357 Figure \refersec{fig:ctemplateexample1source}
2358 can be described in DWARF as illustrated in 
2359 Figure \refersec{fig:ctemplateexample1dwarf}.
2360
2361 \begin{figure}[h]
2362 \begin{lstlisting}
2363 // C++ source
2364 //
2365 template<class T>
2366 struct wrapper {
2367     T comp;
2368 };
2369 wrapper<int> obj;
2370 \end{lstlisting}
2371 \caption{C++ template example \#1: source}
2372 \label{fig:ctemplateexample1source}
2373 \end{figure}
2374
2375 \begin{figure}[h]
2376 \begin{dwflisting}
2377 \begin{alltt}
2378 ! DWARF description
2379 !
2380 11\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2381         \livelink{chap:DWATname}{DW\_AT\_name}("wrapper")
2382 12\$:    \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2383             \livelink{chap:DWATname}{DW\_AT\_name}("T")
2384             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2385 13\$:    \livelink{chap:DWTAGmember}{DW\_TAG\_member}
2386             \livelink{chap:DWATname}{DW\_AT\_name}("comp")
2387             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 12\$)
2388 14\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2389         \livelink{chap:DWATname}{DW\_AT\_name}("obj")
2390         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 11\$)
2391 \end{alltt}
2392 \end{dwflisting}
2393 \caption{C++ template example \#1: DWARF description}
2394 \label{fig:ctemplateexample1dwarf}
2395 \end{figure}
2396
2397 The actual type of the component \texttt{comp} is \texttt{int}, but in the DWARF
2398 the type references the
2399 \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2400 for \texttt{T}, which in turn references \texttt{int}. This implies that in the
2401 original template comp was of type \texttt{T} and that was replaced
2402 with \texttt{int} in the instance. 
2403
2404 \needlines{10}
2405 There exist situations where it is
2406 not possible for the DWARF to imply anything about the nature
2407 of the original template. 
2408 Consider the C++ template source in
2409 Figure \refersec{fig:ctemplateexample2source}
2410 and the DWARF that can describe it in
2411 Figure \refersec{fig:ctemplateexample2dwarf}.
2412
2413 \begin{figure}[!h]
2414 \begin{lstlisting}
2415 // C++ source
2416 //
2417     template<class T>
2418     struct wrapper {
2419         T comp;
2420     };
2421     template<class U>
2422     void consume(wrapper<U> formal)
2423     {
2424         ...
2425     }
2426     wrapper<int> obj;
2427     consume(obj);
2428 \end{lstlisting}
2429 \caption{C++ template example \#2: source}
2430 \label{fig:ctemplateexample2source}
2431 \end{figure}
2432
2433 \begin{figure}[h]
2434 \begin{dwflisting}
2435 \begin{alltt}
2436 ! DWARF description
2437 !
2438 11\$:  \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2439           \livelink{chap:DWATname}{DW\_AT\_name}("wrapper")
2440 12\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2441               \livelink{chap:DWATname}{DW\_AT\_name}("T")
2442               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2443 13\$:      \livelink{chap:DWTAGmember}{DW\_TAG\_member}
2444               \livelink{chap:DWATname}{DW\_AT\_name}("comp")
2445               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 12\$)
2446 14\$:  \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2447           \livelink{chap:DWATname}{DW\_AT\_name}("obj")
2448           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 11\$)
2449 21\$:  \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
2450           \livelink{chap:DWATname}{DW\_AT\_name}("consume")
2451 22\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2452               \livelink{chap:DWATname}{DW\_AT\_name}("U")
2453               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2454 23\$:      \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2455               \livelink{chap:DWATname}{DW\_AT\_name}("formal")
2456               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 11\$)
2457 \end{alltt}
2458 \end{dwflisting}
2459 \caption{C++ template example \#2: DWARF description}
2460 \label{fig:ctemplateexample2dwarf}
2461 \end{figure}
2462
2463 In the \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram} 
2464 entry for the instance of consume, \texttt{U} is described as \texttt{int}. 
2465 The type of formal is \texttt{wrapper\textless U\textgreater} in
2466 the source. DWARF only represents instantiations of templates;
2467 there is no entry which represents \texttt{wrapper\textless U\textgreater} 
2468 which is neither
2469 a template parameter nor a template instantiation. The type
2470 of formal is described as \texttt{wrapper\textless int\textgreater},
2471 the instantiation of \texttt{wrapper\textless U\textgreater},
2472 in the \livelink{chap:DWATtype}{DW\_AT\_type} attribute at 
2473 23\$. 
2474 There is no
2475 description of the relationship between template type parameter
2476 \texttt{T} at 12\$ and \texttt{U} at 22\$ which was used to instantiate
2477 \texttt{wrapper\textless U\textgreater}.
2478
2479 A consequence of this is that the DWARF information would
2480 not distinguish between the existing example and one where
2481 the formal parameter of \texttt{consume} were declared in the source to be
2482 \texttt{wrapper\textless int\textgreater}.
2483
2484
2485 \section{Template Alias Examples}
2486 \label{app:templatealiasexample}
2487
2488 The \addtoindex{C++} template alias shown in
2489 Figure \refersec{fig:ctemplatealiasexample1source}
2490 can be described in DWARF as illustrated 
2491 \addtoindexx{template alias example} in 
2492 Figure \refersec{fig:ctemplatealiasexample1dwarf}.
2493
2494 \begin{figure}[h]
2495 \begin{lstlisting}
2496 // C++ source, template alias example 1
2497 //
2498 template<typename T, typename U>
2499 struct Alpha {
2500     T tango;
2501     U uniform;
2502 };
2503 template<typename V> using Beta = Alpha<V,V>;
2504 Beta<long> b;
2505 \end{lstlisting}
2506 \caption{C++ template alias example \#1: source}
2507 \label{fig:ctemplatealiasexample1source}
2508 \end{figure}
2509
2510 \begin{figure}[h]
2511 \addtoindexx{template alias example 1}
2512 \begin{dwflisting}
2513 \begin{alltt}
2514 ! DWARF representation for variable 'b'
2515 !
2516 20\$:  \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2517           \livelink{chap:DWATname}{DW\_AT\_name}("Alpha")
2518 21\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2519               \livelink{chap:DWATname}{DW\_AT\_name}("T")
2520               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "long")
2521 22\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2522               \livelink{chap:DWATname}{DW\_AT\_name}("U")
2523               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "long")
2524 23\$:      \livelink{chap:DWTAGmember}{DW\_TAG\_member}
2525               \livelink{chap:DWATname}{DW\_AT\_name}("tango")
2526               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 21\$)
2527 24\$:      \livelink{chap:DWTAGmember}{DW\_TAG\_member}
2528               \livelink{chap:DWATname}{DW\_AT\_name}("uniform")
2529               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 22\$)
2530 25\$:  \livelink{chap:DWTAGtemplatealias}{DW\_TAG\_template\_alias}
2531           \livelink{chap:DWATname}{DW\_AT\_name}("Beta")
2532           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 20\$)
2533 26\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2534               \livelink{chap:DWATname}{DW\_AT\_name}("V")
2535               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "long")
2536 27\$:  \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2537           \livelink{chap:DWATname}{DW\_AT\_name}("b")
2538           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 25\$)
2539 \end{alltt}
2540 \end{dwflisting}
2541 \caption{C++ template alias example \#1: DWARF description}
2542 \label{fig:ctemplatealiasexample1dwarf}
2543 \end{figure}
2544
2545 Similarly, the \addtoindex{C++} template alias shown in
2546 Figure \refersec{fig:ctemplatealiasexample2source}
2547 can be described in DWARF as illustrated 
2548 \addtoindexx{template alias example} in 
2549 Figure \refersec{fig:ctemplatealiasexample2dwarf}.
2550
2551 \begin{figure}[h]
2552 \begin{lstlisting}
2553 // C++ source, template alias example 2
2554 //
2555 template<class TX> struct X { };
2556 template<class TY> struct Y { };
2557 template<class T> using Z = Y<T>;
2558 X<Y<int>> y;
2559 X<Z<int>> z;
2560 \end{lstlisting}
2561 \caption{C++ template alias example \#2: source}
2562 \label{fig:ctemplatealiasexample2source}
2563 \end{figure}
2564
2565 \begin{figure}[h]
2566 \addtoindexx{template alias example 2}
2567 \begin{dwflisting}
2568 \begin{alltt}
2569 ! DWARF representation for X<Y<int>>
2570 !
2571 30\$:  \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2572           \livelink{chap:DWATname}{DW\_AT\_name}("Y")
2573 31\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2574               \livelink{chap:DWATname}{DW\_AT\_name}("TY")
2575               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2576 32\$:  \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2577           \livelink{chap:DWATname}{DW\_AT\_name}("X")
2578 33\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2579               \livelink{chap:DWATname}{DW\_AT\_name}("TX")
2580               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 30\$)
2581 !
2582 ! DWARF representation for X<Z<int>>
2583 !
2584 40\$:  \livelink{chap:DWTAGtemplatealias}{DW\_TAG\_template\_alias}
2585           \livelink{chap:DWATname}{DW\_AT\_name}("Z")
2586           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 30\$)
2587 41\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2588               \livelink{chap:DWATname}{DW\_AT\_name}("T")
2589               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2590 42\$:  \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2591           \livelink{chap:DWATname}{DW\_AT\_name}("X")
2592 43\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2593               \livelink{chap:DWATname}{DW\_AT\_name}("TX")
2594               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 40\$)
2595 !
2596 ! Note that 32\$ and 42\$ are actually the same type
2597 !
2598 50\$:  \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2599           \livelink{chap:DWATname}{DW\_AT\_name}("y")
2600           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to \$32)
2601 51\$:  \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2602           \livelink{chap:DWATname}{DW\_AT\_name}("z")
2603           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to \$42)
2604 \end{alltt}
2605 \end{dwflisting}
2606 \caption{C++ template alias example \#2: DWARF description}
2607 \label{fig:ctemplatealiasexample2dwarf}
2608 \end{figure}