Merge branch 'master' of dwarfgit@dwarfstd.org:dwarf-doc.git
[dwarf-doc.git] / dwarf5 / latexdoc / examples.tex
1 \chapter{Examples (Informative)}
2 \label{app:examplesinformative}
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}
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             \livelink{chap:DWOPlit}{DW\_OP\_lit}<n>    ! 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             \livelink{chap:DWOPlit}{DW\_OP\_lit}<n>    ! 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                 \livelink{chap:DWOPlit}{DW\_OP\_lit}<n> ! 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                 \livelink{chap:DWOPlit}{DW\_OP\_lit}<n> ! 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             !  \livelink{chap:DWOPlit}{DW\_OP\_lit}<x> where
388             !       x == 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             \livelink{chap:DWOPlit}{DW\_OP\_lit}<n>                ! where n == offset(ptr\_alloc)
420             \livelink{chap:DWOPplus}{DW\_OP\_plus}
421             \livelink{chap:DWOPderef}{DW\_OP\_deref}
422             \livelink{chap:DWOPlit}{DW\_OP\_lit2}                  ! 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             \livelink{chap:DWOPlit}{DW\_OP\_lit}<n>                ! 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                 \livelink{chap:DWOPlit}{DW\_OP\_lit}<n>            ! 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                 \livelink{chap:DWOPlit}{DW\_OP\_lit}<n>            ! 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 Consider the example in Figure~\ref{fig:assumedrankdecl}, which shows
684 an assumed-rank array in Fortran~2008 with
685 supplement~29113:\footnote{Technical Specification ISO/IEC TS
686   29113:2012 \emph{Further Interoperability of Fortran with C}}
687
688 \begin{figure}[!h]
689 \begin{lstlisting}[language={[95]Fortran}]
690   subroutine foo(x)
691     real :: x(..)
692
693     ! x has n dimensions
694   
695   end subroutine
696 \end{lstlisting}
697 \caption{Declaration of a Fortran 2008 assumed-rank array}
698 \label{fig:assumedrankdecl}
699 \end{figure}
700
701 Let's assume the Fortran compiler used an array descriptor that looks
702 like the one shown in Figure~\ref{fig:arraydesc}.
703
704 \begin{figure}[!h]
705 \begin{lstlisting}[language=C]
706   struct array_descriptor {
707     void *base_addr;
708     int rank;
709     struct dim dims[]; 
710   }
711
712   struct dim {
713      int lower_bound;
714      int upper_bound;
715      int stride;
716      int flags;
717   }
718 \end{lstlisting}
719 \caption{One of many possible layouts for an array descriptor}
720 \label{fig:arraydesc}
721 \end{figure}
722
723 The DWARF type for the array \emph{x} can be described as shown in
724 Figure~\ref{fig:assumedrankdwarf}.
725
726 \begin{figure}[!h]
727 \begin{minipage}[t]{\linewidth}
728 \centering
729 Abbreviation Table: \dotdebugabbrev{}
730 \begin{framed}
731 \scriptsize
732 \begin{alltt}
733 10\$:  \DWTAGarraytype
734          \livelink{chap:DWATtype}{DW\_AT\_type}(reference to real)
735          \livelink{chap:DWATrank}{DW\_AT\_rank}(expression=
736              \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
737              \livelink{chap:DWOPlit}{DW\_OP\_lit}<offset of rank in descriptor>
738              \livelink{chap:DWOPplus}{DW\_OP\_plus}
739              \livelink{chap:DWOPderef}{DW\_OP\_deref})
740          \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location}(expression=
741              \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
742              \livelink{chap:DWOPlit}{DW\_OP\_lit}<offset of data in descriptor>
743              \livelink{chap:DWOPplus}{DW\_OP\_plus}
744              \livelink{chap:DWOPderef}{DW\_OP\_deref})
745 11\$:    \DWTAGgenericsubrange
746              \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
747              \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}(expression=
748              !   Looks up the lower bound of dimension i.
749       
750              !   Operation                              ! Stack effect
751              !   (implicit)                             ! i                                                                     
752                  \livelink{chap:DWOPlit}{DW\_OP\_lit}<byte size of struct dim>     ! i sizeof(dim)
753                  \livelink{chap:DWOPmult}{DW\_OP\_mult}                             ! dim[i]
754                  \livelink{chap:DWOPlit}{DW\_OP\_lit}<offset of dim in descriptor> ! dim[i] offset
755                  \livelink{chap:DWOPplus}{DW\_OP\_plus}                             ! dim[i]+offset
756                  \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}              ! dim[i]+offset objptr
757                  \livelink{chap:DWOPplus}{DW\_OP\_plus}                             ! objptr.dim[i]
758                  \livelink{chap:DWOPlit}{DW\_OP\_lit}<offset of lowerbound in dim> ! objptr.dim[i] offset
759                  \livelink{chap:DWOPplus}{DW\_OP\_plus}                             ! objptr.dim[i].lowerbound
760                  \livelink{chap:DWOPderef}{DW\_OP\_deref})                           ! *objptr.dim[i].lowerbound
761              \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(expression=
762              !   Looks up the upper bound of dimension i.
763                  \livelink{chap:DWOPlit}{DW\_OP\_lit}<byte size of dim>
764                  \livelink{chap:DWOPmult}{DW\_OP\_mult}
765                  \livelink{chap:DWOPlit}{DW\_OP\_lit}<offset of dim in descriptor>
766                  \livelink{chap:DWOPplus}{DW\_OP\_plus}
767                  \livelink{chap:DWOPpushobjectaddress}{DW\_OP\_push\_object\_address}
768                  \livelink{chap:DWOPplus}{DW\_OP\_plus}
769                  \livelink{chap:DWOPlit}{DW\_OP\_lit}<offset of upperbound in dim>
770                  \livelink{chap:DWOPplus}{DW\_OP\_plus}
771                  \livelink{chap:DWOPderef}{DW\_OP\_deref})
772              \livelink{chap:DWATbytestride}{DW\_AT\_byte\_stride}(expression=
773              !   Looks up the byte stride of dimension i.
774                  ...
775              !   (analogous to DW\_AT\_upper\_bound)
776                  )
777 \end{alltt}
778 \end{framed}
779 \end{minipage}
780 \caption{Sample DWARF for the array descriptor in Figure~\ref{fig:arraydesc}}
781 \label{fig:assumedrankdwarf}
782 \end{figure}
783
784 The layout of the array descriptor is not specified by the Fortran
785 standard unless the array is explicitly marked as C-interoperable. To
786 get the bounds of an assumed-rank array, the expressions in the
787 \DWTAGgenericsubrange{} type need to be evaluated for each of the
788 \DWATrank{} dimensions as shown the pseudocode in
789 Figure~\ref{fig:assumedrankdwarfparser}.
790
791 \begin{figure}[!h]
792 \begin{lstlisting}[language=C]
793     typedef struct {
794         int lower, upper, stride;
795     } dims_t;
796
797     typedef struct {
798         int rank;
799     struct dims_t *dims;
800     } array_t;
801
802     array_t get_dynamic_array_dims(DW_TAG_array a) {
803       array_t result;
804
805       // Evaluate the DW_AT_rank expression to get the number of dimensions.
806       dwarf_stack_t stack;
807       dwarf_eval(stack, a.rank_expr);
808       result.rank = dwarf_pop(stack); 
809       result.dims = new dims_t[rank];
810
811       // Iterate over all dimensions and find their bounds.
812       for (int i = 0; i < result.rank; i++) {
813         // Evaluate the generic subrange's DW_AT_lower expression for dimension i.
814         dwarf_push(stack, i);
815         assert( stack.size == 1 );
816         dwarf_eval(stack, a.generic_subrange.lower_expr);
817         result.dims[i].lower = dwarf_pop(stack);
818         assert( stack.size == 0 );
819
820         dwarf_push(stack, i);
821         dwarf_eval(stack, a.generic_subrange.upper_expr);
822         result.dims[i].upper = dwarf_pop(stack);
823     
824         dwarf_push(stack, i);
825         dwarf_eval(stack, a.generic_subrange.byte_stride_expr);
826         result.dims[i].stride = dwarf_pop(stack);
827       }
828       return result;
829     }
830 \end{lstlisting}
831 \caption{How to interpret the DWARF from Figure~\ref{fig:assumedrankdwarf}}
832 \label{fig:assumedrankdwarfparser}
833 \end{figure}
834
835
836
837 \clearpage
838 \subsection{Ada Example}
839 \label{app:adaexample}
840 Figure \refersec{fig:adaexamplesourcefragment}
841 illustrates two kinds of \addtoindex{Ada} 
842 parameterized array, one embedded in a record.
843
844 \begin{figure}[here]
845 \begin{lstlisting}
846 M : INTEGER := <exp>;
847 VEC1 : array (1..M) of INTEGER;
848 subtype TEENY is INTEGER range 1..100;
849 type ARR is array (INTEGER range <>) of INTEGER;
850 type REC2(N : TEENY := 100) is record
851     VEC2 : ARR(1..N);
852 end record;
853
854 OBJ2B : REC2;
855 \end{lstlisting}
856 \caption{Ada example: source fragment}
857 \label{fig:adaexamplesourcefragment}
858 \end{figure}
859
860 \texttt{VEC1} illustrates an (unnamed) array type where the upper bound
861 of the first and only dimension is determined at runtime. 
862 \addtoindex{Ada}
863 semantics require that the value of an array bound is fixed at
864 the time the array type is elaborated (where \textit{elaboration} refers
865 to the runtime executable aspects of type processing). For
866 the purposes of this example, we assume that there are no
867 other assignments to \texttt{M} so that it safe for the \texttt{REC1} type
868 description to refer directly to that variable (rather than
869 a compiler-generated copy).
870
871 \texttt{REC2} illustrates another array type (the unnamed type of
872 component \texttt{VEC2}) where the upper bound of the first and only
873 bound is also determined at runtime. In this case, the upper
874 bound is contained in a discriminant of the containing record
875 type. (A \textit{discriminant} is a component of a record whose value
876 cannot be changed independently of the rest of the record
877 because that value is potentially used in the specification
878 of other components of the record.)
879
880 The DWARF description is shown in 
881 Figure \refersec{fig:adaexampledwarfdescription}.
882
883
884 Interesting aspects about this example are:
885 \begin{enumerate}[1. ]
886 \item The array \texttt{VEC2} is \doublequote{immediately} contained within structure
887 \texttt{REC2} (there is no intermediate descriptor or indirection),
888 which is reflected in the absence of a \livelink{chap:DWATdatalocation}{DW\_AT\_data\_location}
889 attribute on the array type at 28\$.
890
891 \item One of the bounds of \texttt{VEC2} is nonetheless dynamic and part of
892 the same containing record. It is described as a reference to
893 a member, and the location of the upper bound is determined
894 as for any member. That is, the location is determined using
895 an address calculation relative to the base of the containing
896 object.  
897
898 A consumer must notice that the referenced bound is a
899 member of the same containing object and implicitly push the
900 base address of the containing object just as for accessing
901 a data member generally.
902
903 \item The lack of a subtype concept in DWARF means that DWARF types
904 serve the role of subtypes and must replicate information from
905 what should be the parent type. For this reason, DWARF for
906 the unconstrained array type \texttt{ARR} is not needed for the purposes
907 of this example and therefore is not shown.
908 \end{enumerate}
909
910 \begin{figure}[p]
911 \begin{dwflisting}
912 \begin{alltt}
913 11\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
914         \livelink{chap:DWATname}{DW\_AT\_name}("M")
915         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to INTEGER)
916 12\$: \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type}
917         ! No name, default (\addtoindex{Ada}) order, default stride
918         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to INTEGER)
919 13\$:    \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
920             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to INTEGER)
921             \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}(constant 1)
922             \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(reference to variable M at 11\$)
923 14\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
924         \livelink{chap:DWATname}{DW\_AT\_name}("VEC1")
925         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to array type at 12\$)
926      . . .
927 21\$: \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
928         \livelink{chap:DWATname}{DW\_AT\_name}("TEENY")
929         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to INTEGER)
930         \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}(constant 1)
931         \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(constant 100)
932      . . .
933 26\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
934         \livelink{chap:DWATname}{DW\_AT\_name}("REC2")
935 27\$:    \livelink{chap:DWTAGmember}{DW\_TAG\_member}
936             \livelink{chap:DWATname}{DW\_AT\_name}("N")
937             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to subtype TEENY at 21\$)
938             \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}(constant 0)
939 28\$:    \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type}
940             ! No name, default (\addtoindex{Ada}) order, default stride
941             ! Default data location
942             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to INTEGER)
943 29\$:        \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
944                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to subrange TEENY at 21\$)
945                 \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}(constant 1)
946                 \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(reference to member N at 27\$)
947 30\$:    \livelink{chap:DWTAGmember}{DW\_TAG\_member}
948             \livelink{chap:DWATname}{DW\_AT\_name}("VEC2")
949             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to array "subtype" at 28\$)
950             \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location}(machine=
951                 \livelink{chap:DWOPlit}{DW\_OP\_lit}<n> ! where n == offset(REC2, VEC2)
952                 \livelink{chap:DWOPplus}{DW\_OP\_plus})
953      . . .
954 41\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
955         \livelink{chap:DWATname}{DW\_AT\_name}("OBJ2B")
956         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to REC2 at 26\$)
957         \livelink{chap:DWATlocation}{DW\_AT\_location}(...as appropriate...)
958 \end{alltt}
959 \end{dwflisting}
960 \caption{Ada example: DWARF description}
961 \label{fig:adaexampledwarfdescription}
962 \end{figure}
963
964 \clearpage
965
966 \subsection{Pascal Example}
967 \label{app:pascalexample}
968 The Pascal \addtoindexx{Pascal example} source in 
969 Figure \referfol{fig:packedrecordexamplesourcefragment}
970 is used to illustrate the representation of packed unaligned
971 \addtoindex{bit fields}.
972
973 \begin{figure}[here]
974 \begin{lstlisting}
975 TYPE T : PACKED RECORD                  ! bit size is 2
976          F5 : BOOLEAN;                  ! bit offset is 0
977          F6 : BOOLEAN;                  ! bit offset is 1
978          END;
979 VAR V :  PACKED RECORD
980          F1 : BOOLEAN;                  ! bit offset is 0
981          F2 : PACKED RECORD             ! bit offset is 1
982               F3 : INTEGER;             ! bit offset is 0 in F2, 1 in V
983               END;
984          F4 : PACKED ARRAY [0..1] OF T; ! bit offset is 33
985          F7 : T;                        ! bit offset is 37
986          END;
987 \end{lstlisting}
988 \caption{Packed record example: source fragment}
989 \label{fig:packedrecordexamplesourcefragment}
990 \end{figure}
991
992 The DWARF representation in 
993 Figure \refersec{fig:packedrecordexampledwarfdescription} 
994 is appropriate. 
995 \livelink{chap:DWTAGpackedtype}{DW\_TAG\_packed\_type} entries could be added to
996 better represent the source, but these do not otherwise affect
997 the example and are omitted for clarity. Note that this same
998 representation applies to both typical big\dash \ and 
999 little\dash endian
1000 architectures using the conventions described in 
1001 Section \refersec{chap:datamemberentries}.
1002
1003 \begin{figure}[p]
1004 \figurepart{1}{2}
1005 \begin{dwflisting}
1006 \begin{alltt}
1007 10\$: \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
1008         \livelink{chap:DWATname}{DW\_AT\_name}("BOOLEAN")
1009             ...
1010 11\$: \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
1011         \livelink{chap:DWATname}{DW\_AT\_name}("INTEGER")
1012             ...
1013 20\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
1014         \livelink{chap:DWATname}{DW\_AT\_name}("T")
1015         \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(2)
1016         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1017             \livelink{chap:DWATname}{DW\_AT\_name}("F5")
1018             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 10$)
1019             \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}(0)        ! may be omitted
1020             \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(1)
1021         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1022             \livelink{chap:DWATname}{DW\_AT\_name}("F6")
1023             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 10$)
1024             \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}(1)
1025             \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(1)
1026 21\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}                  ! anonymous type for F2
1027         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1028             \livelink{chap:DWATname}{DW\_AT\_name}("F3")
1029             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 11\$)
1030 22\$: \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type}                      ! anonymous type for F4
1031         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 20\$)
1032         \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
1033             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 11\$)
1034             \livelink{chap:DWATlowerbound}{DW\_AT\_lower\_bound}(0)
1035             \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(1)
1036         \livelink{chap:DWATbitstride}{DW\_AT\_bit\_stride}(2)
1037         \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(4) \addtoindexx{bit size attribute}
1038 23\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}                  ! anonymous type for V
1039         \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(39) \addtoindexx{bit size attribute}
1040         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1041             \livelink{chap:DWATname}{DW\_AT\_name}("F1")
1042             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 10\$)
1043             \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}(0)        ! may be omitted
1044             \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(1) ! may be omitted
1045         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1046             \livelink{chap:DWATname}{DW\_AT\_name}("F2")
1047             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 21\$)
1048             \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}(1)
1049             \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(32) ! may be omitted
1050         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1051             \livelink{chap:DWATname}{DW\_AT\_name}("F4")
1052             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 22\$)
1053             \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}(33)
1054             \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(4) ! may be omitted
1055 \end{alltt}
1056 \end{dwflisting}
1057 \caption{Packed record example: DWARF description}
1058 \label{fig:packedrecordexampledwarfdescription}
1059 \end{figure}
1060
1061 \begin{figure}[p]
1062 \figurepart{2}{2}
1063 \begin{dwflisting}
1064 \begin{alltt}
1065         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1066             \livelink{chap:DWATname}{DW\_AT\_name}("F7")
1067             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 20\$)    ! type T
1068             \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}(37)
1069             \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}(2) \addtoindexx{bit size attribute}              ! may be omitted
1070      \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1071         \livelink{chap:DWATname}{DW\_AT\_name}("V")
1072         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 23\$)
1073         \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
1074         ...
1075 \end{alltt}
1076 \end{dwflisting}
1077 \begin{center}
1078 Figure~\ref{fig:packedrecordexampledwarfdescription}: Packed record example: DWARF description \textit{(concluded)}
1079 \end{center}
1080 \end{figure}
1081
1082 \section{Namespace Example}
1083 \label{app:namespaceexample}
1084
1085 The \addtoindex{C++} example in 
1086 Figure \refersec{fig:namespaceexamplesourcefragment}
1087 is used 
1088 \addtoindexx{namespace (C++)!example}
1089 to illustrate the representation of namespaces.
1090 The DWARF representation in 
1091 Figure \refersec{fig:namespaceexampledwarfdescription}
1092 is appropriate.
1093
1094 \begin{figure}[p]
1095 \begin{lstlisting}
1096 namespace {
1097     int i;
1098 }
1099 namespace A {
1100     namespace B {
1101         int j;
1102         int   myfunc (int a);
1103         float myfunc (float f) { return f - 2.0; }
1104         int   myfunc2(int a)   { return a + 2; }
1105     }
1106 }
1107 namespace Y {
1108     using A::B::j;         // (1) using declaration
1109     int foo;
1110 }
1111 using A::B::j;             // (2) using declaration
1112 namespace Foo = A::B;      // (3) namespace alias
1113 using Foo::myfunc;         // (4) using declaration
1114 using namespace Foo;       // (5) using directive
1115 namespace A {
1116     namespace B {
1117         using namespace Y; // (6) using directive
1118         int k;
1119     }
1120 }
1121 int Foo::myfunc(int a)
1122 {
1123     i = 3;
1124     j = 4;
1125     return myfunc2(3) + j + i + a + 2;
1126 }
1127 \end{lstlisting}
1128 \caption{Namespace example: source fragment}
1129 \label{fig:namespaceexamplesourcefragment}
1130 \end{figure}
1131
1132
1133 \begin{figure}[p]
1134 \figurepart{1}{2}
1135 \begin{dwflisting}
1136 \begin{alltt}
1137
1138 1\$:  \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
1139         \livelink{chap:DWATname}{DW\_AT\_name}("int")
1140         ...
1141 2\$:  \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
1142         \livelink{chap:DWATname}{DW\_AT\_name}("float")
1143         ...
1144 6\$:  \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
1145         ! no \livelink{chap:DWATname}{DW\_AT\_name} attribute
1146 7\$:
1147         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1148             \livelink{chap:DWATname}{DW\_AT\_name}("i")
1149             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1150             \livelink{chap:DWATlocation}{DW\_AT\_location} ...
1151             ...
1152 10\$: \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
1153         \livelink{chap:DWATname}{DW\_AT\_name}("A")
1154 20\$:    \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
1155             \livelink{chap:DWATname}{DW\_AT\_name}("B")
1156 30\$:        \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1157                 \livelink{chap:DWATname}{DW\_AT\_name}("j")
1158                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1159                 \livelink{chap:DWATlocation}{DW\_AT\_location} ...
1160                 ...
1161 34\$:        \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1162                 \livelink{chap:DWATname}{DW\_AT\_name}("myfunc")
1163                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1164                 ...
1165 36\$:        \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1166                 \livelink{chap:DWATname}{DW\_AT\_name}("myfunc")
1167                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 2\$)
1168                 ...
1169 38\$:        \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1170                 \livelink{chap:DWATname}{DW\_AT\_name}("myfunc2")
1171                 \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} ...
1172                 \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc} ...
1173                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1174                 ...
1175 \end{alltt}
1176 \end{dwflisting}
1177 \caption{Namespace example: DWARF description}
1178 \label{fig:namespaceexampledwarfdescription}
1179 \end{figure}
1180
1181 \begin{figure}
1182 \figurepart{2}{2}
1183 \begin{dwflisting}
1184 \begin{alltt}
1185 40\$: \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
1186         \livelink{chap:DWATname}{DW\_AT\_name}("Y")
1187         \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}            ! (1) using-declaration
1188             \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 30\$)
1189         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1190             \livelink{chap:DWATname}{DW\_AT\_name}("foo")
1191             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1192             \livelink{chap:DWATlocation}{DW\_AT\_location} ...
1193             ...
1194      \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}               ! (2) using declaration
1195         \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 30\$)
1196         \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}            ! (3) namespace alias
1197             \livelink{chap:DWATname}{DW\_AT\_name}("Foo")
1198             \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 20\$)
1199         \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}            ! (4) using declaration
1200             \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 34\$)     !     - part 1
1201         \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}            ! (4) using declaration
1202             \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 36\$)     !     - part 2
1203         \livelink{chap:DWTAGimportedmodule}{DW\_TAG\_imported\_module}                 ! (5) using directive
1204             \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 20\$)
1205         \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
1206             \livelink{chap:DWATextension}{DW\_AT\_extension}(reference to 10\$)
1207             \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
1208                 \livelink{chap:DWATextension}{DW\_AT\_extension}(reference to 20\$)
1209                 \livelink{chap:DWTAGimportedmodule}{DW\_TAG\_imported\_module}         ! (6) using directive
1210                     \livelink{chap:DWATimport}{DW\_AT\_import}(reference to 40\$)
1211                 \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1212                     \livelink{chap:DWATname}{DW\_AT\_name}("k")
1213                     \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1214                     \livelink{chap:DWATlocation}{DW\_AT\_location} ...
1215                     ...
1216 60\$: \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1217         \livelink{chap:DWATspecification}{DW\_AT\_specification}(reference to 34\$)
1218         \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} ...
1219         \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc} ...
1220         ...
1221 \end{alltt}
1222 \end{dwflisting}
1223 \begin{center}
1224 Figure~\ref{fig:namespaceexampledwarfdescription}: Namespace example: DWARF description \textit{(concluded)}
1225 \end{center}
1226 \end{figure}
1227
1228 \section{Member Function Example}
1229 \label{app:memberfunctionexample}
1230
1231 Consider the member function example fragment in 
1232 Figure \refersec{fig:memberfunctionexamplesourcefragment}.
1233 The DWARF representation in 
1234 Figure \refersec{fig:memberfunctionexampledwarfdescription}
1235 is appropriate.
1236
1237 \begin{figure}[Here]
1238 \begin{lstlisting}
1239 class A
1240 {
1241     void func1(int x1);
1242     void func2() const;
1243     static void func3(int x3);
1244 };
1245 void A::func1(int x) {}
1246 \end{lstlisting}
1247 \caption{Member function example: source fragment}
1248 \label{fig:memberfunctionexamplesourcefragment}
1249 \end{figure}
1250
1251 \begin{figure}[h]
1252 \figurepart{1}{2}
1253 \begin{dwflisting}
1254 \begin{alltt}
1255 1\$: \livelink{chap:DWTAGunspecifiedtype}{DW\_TAG\_unspecified\_type}
1256         \livelink{chap:DWATname}{DW\_AT\_name}("void")
1257                 ...
1258 2\$: \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
1259         \livelink{chap:DWATname}{DW\_AT\_name}("int")
1260         ...
1261 3\$: \livelink{chap:DWTAGclasstype}{DW\_TAG\_class\_type}
1262         \livelink{chap:DWATname}{DW\_AT\_name}("A")
1263         ...
1264 4\$:    \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type}
1265             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 3\$)
1266             ...
1267 5\$:    \livelink{chap:DWTAGconsttype}{DW\_TAG\_const\_type}
1268             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 3\$)
1269             ...
1270 6\$:    \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type}
1271             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 5\$)
1272             ...
1273
1274 7\$:    \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1275             \livelink{chap:DWATdeclaration}{DW\_AT\_declaration}
1276             \livelink{chap:DWATname}{DW\_AT\_name}("func1")
1277             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1278             \livelink{chap:DWATobjectpointer}{DW\_AT\_object\_pointer}(reference to 8\$) \addtoindexx{object pointer attribute}
1279                 ! References a formal parameter in this 
1280                 ! member function
1281             ...
1282 \end{alltt}
1283 \end{dwflisting}
1284 \caption{Member function example: DWARF description}
1285 \label{fig:memberfunctionexampledwarfdescription}
1286 \end{figure}
1287
1288 \begin{figure}[p]
1289 \figurepart{2}{2}
1290 \begin{dwflisting}
1291 \begin{alltt}
1292 8\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1293                 \livelink{chap:DWATartificial}{DW\_AT\_artificial}(true)
1294                 \livelink{chap:DWATname}{DW\_AT\_name}("this")
1295                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 4\$)
1296                     ! Makes type of 'this' as 'A*' =>
1297                     ! func1 has not been marked const 
1298                     ! or volatile
1299                 \livelink{chap:DWATlocation}{DW\_AT\_location} ...
1300                 ...
1301 9\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1302                 \livelink{chap:DWATname}{DW\_AT\_name}(x1)
1303                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 2\$)
1304                 ...
1305 10\$:    \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1306              \livelink{chap:DWATdeclaration}{DW\_AT\_declaration}
1307              \livelink{chap:DWATname}{DW\_AT\_name}("func2")
1308              \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1309              \livelink{chap:DWATobjectpointer}{DW\_AT\_object\_pointer}(reference to 11\$) \addtoindexx{object pointer attribute}
1310              ! References a formal parameter in this 
1311              ! member function
1312              ...
1313 11\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1314                  \livelink{chap:DWATartificial}{DW\_AT\_artificial}(true)
1315                  \livelink{chap:DWATname}{DW\_AT\_name}("this")
1316                  \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 6\$)
1317                  ! Makes type of 'this' as 'A const*' =>
1318                  !     func2 marked as const
1319                  \livelink{chap:DWATlocation}{DW\_AT\_location} ...
1320                  ...
1321 12\$:    \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1322              \livelink{chap:DWATdeclaration}{DW\_AT\_declaration}
1323              \livelink{chap:DWATname}{DW\_AT\_name}("func3")
1324              \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
1325              ...
1326                  ! No object pointer reference formal parameter
1327                  ! implies func3 is static
1328 13\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1329                  \livelink{chap:DWATname}{DW\_AT\_name}(x3)
1330                  \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 2\$)
1331                  ...
1332 \end{alltt}
1333 \end{dwflisting}
1334 \begin{center}
1335 Figure~\ref{fig:memberfunctionexampledwarfdescription}: Member function example: DWARF description \textit{(concluded)}
1336 \end{center}
1337 \end{figure}
1338
1339 \clearpage
1340 \section{Line Number Program Example}
1341 \label{app:linenumberprogramexample}
1342
1343 Consider the simple source file and the resulting machine
1344 code for the Intel 8086 processor in 
1345 Figure \refersec{fig:linenumberprogramexamplemachinecode}.
1346
1347 \begin{figure}[here]
1348 \begin{lstlisting}
1349 1: int
1350 2: main()
1351     0x239: push pb
1352     0x23a: mov bp,sp
1353 3: {
1354 4: printf("Omit needless words\n");
1355     0x23c: mov ax,0xaa
1356     0x23f: push ax
1357     0x240: call _printf
1358     0x243: pop cx
1359 5: exit(0);
1360     0x244: xor ax,ax
1361     0x246: push ax
1362     0x247: call _exit
1363     0x24a: pop cx
1364 6: }
1365     0x24b: pop bp
1366     0x24c: ret
1367 7: 0x24d:
1368 \end{lstlisting}
1369 \caption{Line number program example: machine code}
1370 \label{fig:linenumberprogramexamplemachinecode}
1371 \end{figure}
1372
1373 Suppose the line number program header includes the following
1374 (header fields not needed 
1375 \addtoindexx{line\_base}
1376 below 
1377 \addtoindexx{line\_range}
1378 are 
1379 \addtoindexx{opcode\_base}
1380 not 
1381 \addtoindexx{minumum\_instruction\_length}
1382 shown):
1383 \begin{alltt}
1384     version                       4
1385     minimum_instruction_length    1
1386     opcode_base                  10   ! Opcodes 10-12 not needed
1387     line_base                     1
1388     line_range                   15
1389 \end{alltt}
1390
1391
1392 Table \refersec{tab:linenumberprogramexampleoneencoding}
1393 shows one encoding of the line number program, which occupies
1394 12 bytes (the opcode SPECIAL(\textit{m},\textit{n}) indicates the special opcode
1395 generated for a line increment of \textit{m} and an address increment
1396 of \textit{n}).
1397
1398 \newpage
1399 \begin{centering}
1400 \setlength{\extrarowheight}{0.1cm}
1401 \begin{longtable}{l|l|l}
1402   \caption{Line number program example: one \mbox{encoding}}
1403   \label{tab:linenumberprogramexampleoneencoding} \\
1404   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
1405 \endfirsthead
1406   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
1407 \endhead
1408   \hline \emph{Continued on next page}
1409 \endfoot
1410   \hline
1411 \endlastfoot
1412 \livelink{chap:DWLNSadvancepc}{DW\_LNS\_advance\_pc}&LEB128(0x239)&0x2, 0xb9, 0x04 \\
1413 SPECIAL(2, 0)& &0xb  \\
1414 SPECIAL(2, 3)& &0x38 \\
1415 SPECIAL(1, 8)& &0x82 \\
1416 SPECIAL(1, 7)& &0x73 \\
1417 \livelink{chap:DWLNSadvancepc}{DW\_LNS\_advance\_pc}&LEB128(2)&0x2, 0x2 \\
1418 \livelink{chap:DWLNEendsequence}{DW\_LNE\_end\_sequence} &&0x0, 0x1, 0x1 \\
1419 \end{longtable}
1420 \end{centering}
1421
1422
1423 Table \refersec{tab:linenumberprogramexamplealternateencoding}
1424 shows an alternate 
1425 encoding of the same program using 
1426 standard opcodes to advance
1427 the program counter; 
1428 this encoding occupies 22 bytes.
1429
1430 \begin{centering}
1431 \setlength{\extrarowheight}{0.1cm}
1432 \begin{longtable}{l|l|l}
1433   \caption{Line number program example: alternate encoding} 
1434   \label{tab:linenumberprogramexamplealternateencoding} \\
1435   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
1436 \endfirsthead
1437   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
1438 \endhead
1439   \hline \emph{Continued on next page}
1440 \endfoot
1441   \hline
1442 \endlastfoot
1443 \livelink{chap:DWLNSfixedadvancepc}{DW\_LNS\_fixed\_advance\_pc}&0x239&0x9, 0x39, 0x2        \\
1444 SPECIAL(2, 0)&& 0xb        \\
1445 \livelink{chap:DWLNSfixedadvancepc}{DW\_LNS\_fixed\_advance\_pc}&0x3&0x9, 0x3, 0x0        \\
1446 SPECIAL(2, 0)&&0xb        \\
1447 \livelink{chap:DWLNSfixedadvancepc}{DW\_LNS\_fixed\_advance\_pc}&0x8&0x9, 0x8, 0x0        \\
1448 SPECIAL(1, 0)&& 0xa        \\
1449 \livelink{chap:DWLNSfixedadvancepc}{DW\_LNS\_fixed\_advance\_pc}&0x7&0x9, 0x7, 0x0        \\
1450 SPECIAL(1, 0) && 0xa        \\
1451 \livelink{chap:DWLNSfixedadvancepc}{DW\_LNS\_fixed\_advance\_pc}&0x2&0x9, 0x2, 0x0        \\
1452 \livelink{chap:DWLNEendsequence}{DW\_LNE\_end\_sequence}&&0x0, 0x1, 0x1        \\
1453 \end{longtable}
1454 \end{centering}
1455
1456
1457 \section{Call Frame Information Example}
1458 \label{app:callframeinformationexample}
1459
1460 The following example uses a hypothetical RISC machine in
1461 the style of the Motorola 88000.
1462 \begin{itemize}
1463 \item Memory is byte addressed.
1464
1465 \item Instructions are all 4 bytes each and word aligned.
1466
1467 \item Instruction operands are typically of the form:
1468 \begin{alltt}
1469     <destination.reg>, <source.reg>, <constant>
1470 \end{alltt}
1471
1472 \item The address for the load and store instructions is computed
1473 by adding the contents of the
1474 source register with the constant.
1475
1476 \item There are eight 4\dash byte registers:
1477 \newline
1478 \begin{tabular}{p{5mm}l}
1479    & R0 always 0 \\
1480    & R1 holds return address on call \\
1481    & R2-R3 temp registers (not preserved on call) \\
1482    & R4-R6 preserved on call \\
1483    & R7 stack pointer \\
1484 \end{tabular}
1485
1486 \item  The stack grows in the negative direction.
1487
1488 \item The architectural ABI committee specifies that the
1489 stack pointer (R7) is the same as the CFA
1490
1491 \end{itemize}
1492
1493 Figure \referfol{fig:callframeinformationexamplemachinecodefragments}
1494 shows two code fragments from a subroutine called
1495 foo that uses a frame pointer (in addition to the stack
1496 pointer). The first column values are byte addresses. 
1497 % The \space is so we get a space after >
1498 \textless fs\textgreater\ denotes the stack frame size in bytes, namely 12.
1499
1500
1501 \begin{figure}[here]
1502 \begin{lstlisting}
1503        ;; start prologue
1504 foo    sub   R7, R7, <fs>        ; Allocate frame
1505 foo+4  store R1, R7, (<fs>-4)    ; Save the return address
1506 foo+8  store R6, R7, (<fs>-8)    ; Save R6
1507 foo+12 add   R6, R7, 0           ; R6 is now the Frame ptr
1508 foo+16 store R4, R6, (<fs>-12)   ; Save a preserved reg
1509        ;; This subroutine does not change R5
1510        ...
1511        ;; Start epilogue (R7 is returned to entry value)
1512 foo+64 load  R4, R6, (<fs>-12)   ; Restore R4
1513 foo+68 load  R6, R7, (<fs>-8)    ; Restore R6
1514 foo+72 load  R1, R7, (<fs>-4)    ; Restore return address
1515 foo+76 add   R7, R7, <fs>        ; Deallocate frame
1516 foo+80 jump  R1                  ; Return
1517 foo+84
1518 \end{lstlisting}
1519 \caption{Call frame information example: machine code fragments}
1520 \label{fig:callframeinformationexamplemachinecodefragments}
1521 \end{figure}
1522
1523
1524 An abstract table 
1525 (see Section \refersec{chap:structureofcallframeinformation}) 
1526 for the foo subroutine is shown in 
1527 Table \referfol{tab:callframeinformationexampleconceptualmatrix}.
1528 Corresponding fragments from the
1529 \dotdebugframe{} section are shown in 
1530 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
1531
1532 The following notations apply in 
1533 Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
1534 \newline
1535 \begin{tabular}{p{5mm}l}
1536 &1.  R8 is the return address \\
1537 &2.  s = same\_value rule \\
1538 &3.  u = undefined rule \\
1539 &4.  rN = register(N) rule \\
1540 &5.  cN = offset(N) rule \\
1541 &6.  a = architectural rule \\
1542 \end{tabular}
1543
1544 \begin{centering}
1545 \setlength{\extrarowheight}{0.1cm}
1546 \begin{longtable}{l|llllllllll}
1547   \caption{Call frame information example: conceptual matrix} 
1548   \label{tab:callframeinformationexampleconceptualmatrix} \\
1549   \hline \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
1550 \endfirsthead
1551   \bfseries Location &\bfseries CFA &\bfseries R0 & \bfseries R1 & \bfseries R2 &\bfseries R3 &\bfseries R4 &\bfseries R5 &\bfseries R6 &\bfseries R7 &\bfseries R8\\ \hline
1552 \endhead
1553   \hline \emph{Continued on next page}
1554 \endfoot
1555   \hline
1556 \endlastfoot
1557 foo&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
1558 foo+4&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
1559 foo+8&[R7]+fs&s&u&u&u&s&s&s&a&c-4 \\
1560 foo+12&[R7]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
1561 foo+16&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
1562 foo+20&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
1563 ...&&&&&&&&&& \\
1564 foo+64&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
1565 foo+68&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4  \\
1566 foo+72&[R7]+fs&s&u&u&u&s&s&s&a&c-4  \\
1567 foo+76&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
1568 foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
1569 \end{longtable}
1570 \end{centering}
1571
1572 \clearpage      % ?????
1573
1574 \begin{centering}
1575 \setlength{\extrarowheight}{0.1cm}
1576 \begin{longtable}{l|ll}
1577   \caption{Call frame information example: common information entry encoding} 
1578   \label{tab:callframeinformationexamplecommoninformationentryencoding} 
1579   \\
1580   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1581 \endfirsthead
1582   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1583 \endhead
1584   \hline \emph{Continued on next page}
1585 \endfoot
1586   \hline
1587 \endlastfoot
1588 cie&36&length    \\
1589 cie+4&\xffffffff&CIE\_id    \\
1590 cie+8&4&version    \\
1591 cie+9&0&augmentation     \\
1592 cie+10&4&address size    \\
1593 cie+11&0&segment size    \\
1594 cie+12&4&code\_alignment\_factor, \textless caf \textgreater    \\
1595 cie+13&-4&data\_alignment\_factor, \textless daf \textgreater    \\
1596 cie+14&8&R8 is the return addr.    \\
1597 cie+15&\livelink{chap:DWCFAdefcfa}{DW\_CFA\_def\_cfa} (7, 0)&CFA = [R7]+0    \\
1598 cie+18&\livelink{chap:DWCFAsamevalue}{DW\_CFA\_same\_value} (0)&R0 not modified (=0)    \\
1599 cie+20&\livelink{chap:DWCFAundefined}{DW\_CFA\_undefined} (1)&R1 scratch    \\
1600 cie+22&\livelink{chap:DWCFAundefined}{DW\_CFA\_undefined} (2)&R2 scratch    \\
1601 cie+24&\livelink{chap:DWCFAundefined}{DW\_CFA\_undefined} (3)&R3 scratch    \\
1602 cie+26&\livelink{chap:DWCFAsamevalue}{DW\_CFA\_same\_value} (4)&R4 preserve    \\
1603 cie+28&\livelink{chap:DWCFAsamevalue}{DW\_CFA\_same\_value} (5)&R5 preserve    \\
1604 cie+30&\livelink{chap:DWCFAsamevalue}{DW\_CFA\_same\_value} (6)&R6 preserve    \\
1605 cie+32&\livelink{chap:DWCFAsamevalue}{DW\_CFA\_same\_value} (7)&R7 preserve    \\
1606 cie+34&\livelink{chap:DWCFAregister}{DW\_CFA\_register} (8, 1)&R8 is in R1    \\
1607 cie+37&\livelink{chap:DWCFAnop}{DW\_CFA\_nop} &padding    \\
1608 cie+38&\livelink{chap:DWCFAnop}{DW\_CFA\_nop} &padding \\
1609 cie+39& \livelink{chap:DWCFAnop}{DW\_CFA\_nop}&padding  \\
1610 cie+40 &&  \\
1611 \end{longtable}
1612 \end{centering}
1613
1614
1615 The following notations apply in 
1616 Table \refersec{tab:callframeinformationexampleframedescriptionentryencoding}:
1617 \newline
1618 \begin{tabular}{p{5mm}l}
1619 &\texttt{<fs>  =} frame size \\
1620 &\texttt{<caf> =} code alignment factor \\
1621 &\texttt{<daf> =} data alignment factor \\
1622 \end{tabular}
1623
1624
1625 \begin{centering}
1626 \setlength{\extrarowheight}{0.1cm}
1627 \begin{longtable}{l|ll}
1628   \caption{Call frame information example: frame description entry encoding} 
1629   \label{tab:callframeinformationexampleframedescriptionentryencoding} \\
1630   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1631 \endfirsthead
1632   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1633 \endhead
1634   \hline \emph{Continued on next page}
1635 \endfoot
1636   \hline
1637 \endlastfoot
1638 fde&40&length \\
1639 fde+4&cie&CIE\_ptr \\
1640 fde+8&foo&initial\_location \\
1641 fde+12&84&address\_range \\
1642 fde+16&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1)&instructions \\
1643 fde+17&\livelink{chap:DWCFAdefcfaoffset}{DW\_CFA\_def\_cfa\_offset}(12)& \textless fs\textgreater \\
1644 fde+19&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1)&4/\textless caf\textgreater \\
1645 fde+20&\livelink{chap:DWCFAoffset}{DW\_CFA\_offset}(8,1)&-4/\textless daf\textgreater (2nd parameter) \\
1646 fde+22&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1)& \\
1647 fde+23&\livelink{chap:DWCFAoffset}{DW\_CFA\_offset}(6,2)&-8/\textless daf\textgreater (2nd parameter)  \\
1648 fde+25&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1) & \\
1649 fde+26&\livelink{chap:DWCFAdefcfaregister}{DW\_CFA\_def\_cfa\_register}(6) & \\
1650 fde+28&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1) & \\
1651 fde+29&\livelink{chap:DWCFAoffset}{DW\_CFA\_offset}(4,3)&-12/\textless daf\textgreater (2nd parameter) \\
1652 fde+31&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(12)&44/\textless caf\textgreater \\
1653 fde+32&\livelink{chap:DWCFArestore}{DW\_CFA\_restore}(4)& \\
1654 fde+33&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1) & \\
1655 fde+34&\livelink{chap:DWCFArestore}{DW\_CFA\_restore}(6) & \\
1656 fde+35&\livelink{chap:DWCFAdefcfaregister}{DW\_CFA\_def\_cfa\_register}(7)  & \\
1657 fde+37&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1) & \\
1658 fde+38&\livelink{chap:DWCFArestore}{DW\_CFA\_restore}(8) &\\
1659 fde+39&\livelink{chap:DWCFAadvanceloc}{DW\_CFA\_advance\_loc}(1) &\\
1660 fde+40&\livelink{chap:DWCFAdefcfaoffset}{DW\_CFA\_def\_cfa\_offset}(0)  &\\
1661 fde+42&\livelink{chap:DWCFAnop}{DW\_CFA\_nop}&padding \\
1662 fde+43&\livelink{chap:DWCFAnop}{DW\_CFA\_nop}&padding \\
1663 fde+44 && \\
1664 \end{longtable}
1665 \end{centering}
1666
1667 \section{Inlining Examples}
1668 \label{app:inliningexamples}
1669 The pseudo\dash source in 
1670 Figure \referfol{fig:inliningexamplespseudosourcefragment}
1671 is used to illustrate the
1672 \addtoindexx{inlined subprogram call!examples}
1673 use of DWARF to describe inlined subroutine calls. This
1674 example involves a nested subprogram \texttt{INNER} that makes uplevel
1675 references to the formal parameter and local variable of the
1676 containing subprogram \texttt{OUTER}.
1677
1678 \begin{figure}[here]
1679 \begin{lstlisting}
1680 inline procedure OUTER (OUTER_FORMAL : integer) =
1681     begin
1682     OUTER_LOCAL : integer;
1683     procedure INNER (INNER_FORMAL : integer) =
1684         begin
1685         INNER_LOCAL : integer;
1686         print(INNER_FORMAL + OUTER_LOCAL);
1687         end;
1688     INNER(OUTER_LOCAL);
1689     ...
1690     INNER(31);
1691     end;
1692 ! Call OUTER
1693 !
1694 OUTER(7);
1695 \end{lstlisting}
1696 \caption{Inlining examples: pseudo-source fragmment} 
1697 \label{fig:inliningexamplespseudosourcefragment}
1698 \end{figure}
1699
1700
1701 There are several approaches that a compiler might take to
1702 inlining for this sort of example. This presentation considers
1703 three such approaches, all of which involve inline expansion
1704 of subprogram \texttt{OUTER}. (If \texttt{OUTER} is not inlined, the inlining
1705 reduces to a simpler single level subset of the two level
1706 approaches considered here.)
1707
1708 The approaches are:
1709 \begin{enumerate}[1. ]
1710 \item  Inline both \texttt{OUTER} and \texttt{INNER} in all cases
1711
1712 \item Inline \texttt{OUTER}, multiple \texttt{INNER}s \\
1713 Treat \texttt{INNER} as a non\dash inlinable part of \texttt{OUTER}, compile and
1714 call a distinct normal version of \texttt{INNER} defined within each
1715 inlining of \texttt{OUTER}.
1716
1717 \item Inline \texttt{OUTER}, one \texttt{INNER} \\
1718 Compile \texttt{INNER} as a single normal subprogram which is called
1719 from every inlining of \texttt{OUTER}.
1720 \end{enumerate}
1721
1722 This discussion does not consider why a compiler might choose
1723 one of these approaches; it considers only how to describe
1724 the result.
1725
1726 In the examples that follow in this section, the debugging
1727 information entries are given mnemonic labels of the following
1728 form
1729 \begin{verbatim}
1730     <io>.<ac>.<n>.<s>
1731 \end{verbatim}
1732 where
1733 \begin{description}
1734 \item[\textless io\textgreater]
1735 is either \texttt{INNER} or \texttt{OUTER} to indicate to which
1736 subprogram the debugging information entry applies, 
1737 \item[\textless ac\textgreater]
1738 is either AI or CI to indicate \doublequote{abstract instance} or
1739 \doublequote{concrete instance} respectively, 
1740 \item[\textless n\textgreater]
1741 is the number of the
1742 alternative being considered, and 
1743 \item[\textless s\textgreater]
1744 is a sequence number that
1745 distinguishes the individual entries. 
1746 \end{description}
1747 There is no implication
1748 that symbolic labels, nor any particular naming convention,
1749 are required in actual use.
1750
1751 For conciseness, declaration coordinates and call coordinates are omitted.
1752
1753 \subsection{Alternative \#1: inline both OUTER and INNER}
1754 \label{app:inlinebothouterandinner}
1755
1756 A suitable abstract instance for an alternative where both
1757 \texttt{OUTER} and \texttt{INNER} are always inlined is shown in 
1758 Figure \refersec{fig:inliningexample1abstractinstance}.
1759
1760 Notice in 
1761 Figure \ref{fig:inliningexample1abstractinstance} 
1762 that the debugging information entry for
1763 \texttt{INNER} (labelled \texttt{INNER.AI.1.1}) is nested in (is a child of)
1764 that for \texttt{OUTER} (labelled \texttt{OUTER.AI.1.1}). Nonetheless, the
1765 abstract instance tree for \texttt{INNER} is considered to be separate
1766 and distinct from that for \texttt{OUTER}.
1767
1768 The call of \texttt{OUTER} shown in 
1769 Figure \refersec{fig:inliningexamplespseudosourcefragment}
1770 might be described as
1771 shown in 
1772 Figure \refersec{fig:inliningexample1concreteinstance}.
1773
1774
1775 \begin{figure}[p]
1776 \begin{dwflisting}
1777 \begin{alltt}
1778     ! Abstract instance for OUTER
1779     ! \addtoindexx{abstract instance!example}
1780 OUTER.AI.1.1:
1781     \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1782         \livelink{chap:DWATname}{DW\_AT\_name}("OUTER")
1783         \livelink{chap:DWATinline}{DW\_AT\_inline}(\livelink{chap:DWINLdeclaredinlined}{DW\_INL\_declared\_inlined})
1784         ! No low/high PCs
1785 OUTER.AI.1.2:
1786         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1787             \livelink{chap:DWATname}{DW\_AT\_name}("OUTER\_FORMAL")
1788             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1789             ! No location
1790 OUTER.AI.1.3:
1791         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1792             \livelink{chap:DWATname}{DW\_AT\_name}("OUTER\_LOCAL")
1793             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1794             ! No location
1795         !
1796         ! Abstract instance for INNER
1797         !
1798 INNER.AI.1.1:
1799         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1800             \livelink{chap:DWATname}{DW\_AT\_name}("INNER")
1801             \livelink{chap:DWATinline}{DW\_AT\_inline}(\livelink{chap:DWINLdeclaredinlined}{DW\_INL\_declared\_inlined})
1802             ! No low/high PCs
1803 INNER.AI.1.2:
1804             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1805                 \livelink{chap:DWATname}{DW\_AT\_name}("INNER\_FORMAL")
1806                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1807                 ! No location
1808 INNER.AI.1.3:
1809             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1810                 \livelink{chap:DWATname}{DW\_AT\_name}("INNER\_LOCAL")
1811                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1812                 ! No location
1813             ...
1814             0
1815         ! No \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine} (concrete instance)
1816         ! for INNER corresponding to calls of INNER
1817         ...
1818         0
1819 \end{alltt}
1820 \end{dwflisting}
1821 \caption{Inlining example \#1: abstract instance}
1822 \label{fig:inliningexample1abstractinstance}
1823 \end{figure}
1824
1825 \begin{figure}[p]
1826 \begin{dwflisting}
1827 \begin{alltt}
1828 ! Concrete instance for call "OUTER(7)"
1829 ! \addtoindexx{concrete instance!example}
1830 OUTER.CI.1.1:
1831     \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
1832         ! No name
1833         \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.1.1)
1834         \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}(...)
1835         \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}(...)
1836 OUTER.CI.1.2:
1837         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1838             ! No name
1839             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.1.2)
1840             \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}(7)
1841 OUTER.CI.1.3:
1842         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1843             ! No name
1844             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.1.3)
1845             \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
1846         !
1847         ! No \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram} (abstract instance) for INNER
1848         !
1849         ! Concrete instance for call INNER(OUTER\_LOCAL)
1850         !
1851 INNER.CI.1.1:
1852         \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
1853             ! No name
1854             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to INNER.AI.1.1)
1855             \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}(...)
1856             \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}(...)
1857             \livelink{chap:DWATstaticlink}{DW\_AT\_static\_link}(...)
1858 INNER.CI.1.2:
1859             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1860                 ! No name
1861                 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to INNER.AI.1.2)
1862                 \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
1863 INNER.CI.1.3:
1864             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1865                 ! No name
1866                 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to INNER.AI.1.3)
1867                 \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
1868             ...
1869             0
1870         ! Another concrete instance of INNER within OUTER
1871         ! for the call "INNER(31)"
1872         ...
1873         0
1874 \end{alltt}
1875 \end{dwflisting}
1876 \caption{Inlining example \#1: concrete instance}
1877 \label{fig:inliningexample1concreteinstance}
1878 \end{figure}
1879
1880 \subsection{Alternative \#2: Inline OUTER, multiple INNERs}
1881 \label{app:inlineoutermultiipleinners}
1882
1883
1884 In the second alternative we assume that subprogram \texttt{INNER}
1885 is not inlinable for some reason, but subprogram \texttt{OUTER} is
1886 inlinable. 
1887 \addtoindexx{concrete instance!example}
1888 Each concrete inlined instance of \texttt{OUTER} has its
1889 own normal instance of \texttt{INNER}. 
1890 The abstract instance for \texttt{OUTER},
1891 \addtoindexx{abstract instance!example}
1892 which includes \texttt{INNER}, is shown in 
1893 Figure \refersec{fig:inliningexample2abstractinstance}.
1894
1895 Note that the debugging information in 
1896 Figure \ref{fig:inliningexample2abstractinstance}
1897 differs from that in 
1898 Figure \refersec{fig:inliningexample1abstractinstance}
1899 in that \texttt{INNER} lacks a 
1900 \livelink{chap:DWATinline}{DW\_AT\_inline} attribute
1901 and therefore is not a distinct abstract instance. \texttt{INNER}
1902 is merely an out\dash of\dash line routine that is part of \texttt{OUTER}\textquoteright s
1903 abstract instance. This is reflected in the Figure by
1904 \addtoindexx{abstract instance!example}
1905 the fact that the labels for \texttt{INNER} use the substring \texttt{OUTER}
1906 instead of \texttt{INNER}.
1907
1908 A resulting 
1909 \addtoindexx{concrete instance!example}
1910 concrete inlined instance of \texttt{OUTER} is shown in
1911 Figure \refersec{fig:inliningexample2concreteinstance}.
1912
1913 Notice in 
1914 Figure \ref{fig:inliningexample2concreteinstance}
1915 that \texttt{OUTER} is expanded as a concrete
1916 \addtoindexx{concrete instance!example}
1917 inlined instance, and that \texttt{INNER} is nested within it as a
1918 concrete out\dash of\dash line subprogram. Because \texttt{INNER} is cloned
1919 for each inline expansion of \texttt{OUTER}, only the invariant
1920 attributes of \texttt{INNER} 
1921 (for example, \livelink{chap:DWATname}{DW\_AT\_name}) are specified
1922 in the abstract instance of \texttt{OUTER}, and the low\dash level,
1923 \addtoindexx{abstract instance!example}
1924 instance\dash specific attributes of \texttt{INNER} (for example,
1925 \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}) are specified in 
1926 each concrete instance of \texttt{OUTER}.
1927 \addtoindexx{concrete instance!example}
1928
1929 The several calls of \texttt{INNER} within \texttt{OUTER} are compiled as normal
1930 calls to the instance of \texttt{INNER} that is specific to the same
1931 instance of \texttt{OUTER} that contains the calls.
1932
1933 \begin{figure}[t]
1934 \begin{dwflisting}
1935 \begin{alltt}
1936     ! Abstract instance for OUTER
1937     ! \addtoindex{abstract instance}
1938 OUTER.AI.2.1:
1939     \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1940         \livelink{chap:DWATname}{DW\_AT\_name}("OUTER")
1941         \livelink{chap:DWATinline}{DW\_AT\_inline}(\livelink{chap:DWINLdeclaredinlined}{DW\_INL\_declared\_inlined})
1942         ! No low/high PCs
1943 OUTER.AI.2.2:
1944         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1945             \livelink{chap:DWATname}{DW\_AT\_name}("OUTER\_FORMAL")
1946             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1947             ! No location
1948 OUTER.AI.2.3:
1949         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1950             \livelink{chap:DWATname}{DW\_AT\_name}("OUTER\_LOCAL")
1951             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1952             ! No location
1953         !
1954         ! Nested out-of-line INNER subprogram
1955         !
1956 OUTER.AI.2.4:
1957         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1958             \livelink{chap:DWATname}{DW\_AT\_name}("INNER")
1959             ! No \livelink{chap:DWATinline}{DW\_AT\_inline}
1960             ! No low/high PCs, frame\_base, etc.
1961 OUTER.AI.2.5:
1962             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1963                 \livelink{chap:DWATname}{DW\_AT\_name}("INNER\_FORMAL")
1964                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1965                 ! No location
1966 OUTER.AI.2.6:
1967             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1968                 \livelink{chap:DWATname}{DW\_AT\_name}("INNER\_LOCAL")
1969                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
1970                 ! No location
1971             ...
1972             0
1973         ...
1974         0
1975 \end{alltt}
1976 \end{dwflisting}
1977 \caption{Inlining example \#2: abstract instance}
1978 \label{fig:inliningexample2abstractinstance}
1979 \end{figure}
1980
1981 \begin{figure}[t]
1982 \begin{dwflisting}
1983 \begin{alltt}
1984
1985     ! Concrete instance for call "OUTER(7)"
1986     !
1987 OUTER.CI.2.1:
1988     \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
1989         ! No name
1990         \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.2.1)
1991         \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}(...)
1992         \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}(...)
1993 OUTER.CI.2.2:
1994         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1995             ! No name
1996             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.2.2)
1997             \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
1998 OUTER.CI.2.3:
1999         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2000             ! No name
2001             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.2.3)
2002             \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2003         !
2004         ! Nested out-of-line INNER subprogram
2005         !
2006 OUTER.CI.2.4:
2007         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
2008             ! No name
2009             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.2.4)
2010             \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}(...)
2011             \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}(...)
2012             \livelink{chap:DWATframebase}{DW\_AT\_frame\_base}(...)
2013             \livelink{chap:DWATstaticlink}{DW\_AT\_static\_link}(...)
2014 OUTER.CI.2.5:
2015             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2016                 ! No name
2017                 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.2.5)
2018                 \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2019 OUTER.CI.2.6:
2020             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2021                 ! No name
2022                 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AT.2.6)
2023                 \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2024             ...
2025             0
2026         ...
2027         0
2028 \end{alltt}
2029 \end{dwflisting}
2030 \caption{Inlining example \#2: concrete instance}
2031 \label{fig:inliningexample2concreteinstance}
2032 \end{figure}
2033
2034 \subsection{Alternative \#3: inline OUTER, one normal INNER}
2035 \label{app:inlineouteronenormalinner}
2036
2037 In the third approach, one normal subprogram for \texttt{INNER} is
2038 compiled which is called from all concrete inlined instances of
2039 \addtoindexx{concrete instance!example}
2040 \addtoindexx{abstract instance!example}
2041 \texttt{OUTER}. The abstract instance for \texttt{OUTER} is shown in 
2042 Figure \refersec{fig:inliningexample3abstractinstance}.
2043
2044 The most distinctive aspect of that Figure is that subprogram
2045 \texttt{INNER} exists only within the abstract instance of \texttt{OUTER},
2046 and not in \texttt{OUTER}\textquoteright s concrete instance. In the abstract
2047 \addtoindexx{concrete instance!example}
2048 \addtoindexx{abstract instance!example}
2049 instance of \texttt{OUTER}, the description of \texttt{INNER} has the full
2050 complement of attributes that would be expected for a
2051 normal subprogram. 
2052 While attributes such as 
2053 \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc},
2054 \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}, 
2055 \livelink{chap:DWATlocation}{DW\_AT\_location},
2056 and so on, typically are omitted
2057 \addtoindexx{high PC attribute}
2058 from 
2059 \addtoindexx{low PC attribute}
2060 an 
2061 \addtoindexx{location attribute}
2062 abstract instance because they are not invariant across
2063 instances of the containing abstract instance, in this case
2064 those same attributes are included precisely because they are
2065 invariant -- there is only one subprogram \texttt{INNER} to be described
2066 and every description is the same.
2067
2068 A concrete inlined instance of \texttt{OUTER} is illustrated in
2069 Figure \refersec{fig:inliningexample3concreteinstance}.
2070
2071 Notice in 
2072 Figure \ref{fig:inliningexample3concreteinstance}
2073 that there is no DWARF representation for
2074 \texttt{INNER} at all; the representation of \texttt{INNER} does not vary across
2075 instances of \texttt{OUTER} and the abstract instance of \texttt{OUTER} includes
2076 the complete description of \texttt{INNER}, so that the description of
2077 \texttt{INNER} may be (and for reasons of space efficiency, should be)
2078 omitted from each 
2079 \addtoindexx{concrete instance!example}
2080 concrete instance of \texttt{OUTER}.
2081
2082 There is one aspect of this approach that is problematical from
2083 the DWARF perspective. The single compiled instance of \texttt{INNER}
2084 is assumed to access up\dash level variables of \texttt{OUTER}; however,
2085 those variables may well occur at varying positions within
2086 the frames that contain the 
2087 \addtoindexx{concrete instance!example}
2088 concrete inlined instances. A
2089 compiler might implement this in several ways, including the
2090 use of additional compiler-generated parameters that provide
2091 reference parameters for the up\dash level variables, or a 
2092 compiler-generated static link like parameter that points to the group
2093 of up\dash level entities, among other possibilities. In either of
2094 these cases, the DWARF description for the location attribute
2095 of each uplevel variable needs to be different if accessed
2096 from within \texttt{INNER} compared to when accessed from within the
2097 instances of \texttt{OUTER}. An implementation is likely to require
2098 vendor\dash specific DWARF attributes and/or debugging information
2099 entries to describe such cases.
2100
2101 Note that in C++, a member function of a class defined within
2102 a function definition does not require any vendor\dash specific
2103 extensions because the C++ language disallows access to
2104 entities that would give rise to this problem. (Neither \texttt{extern}
2105 variables nor \texttt{static} members require any form of static link
2106 for accessing purposes.)
2107
2108 \begin{figure}[t]
2109 \begin{dwflisting}
2110 \begin{alltt}
2111     ! Abstract instance for OUTER
2112     ! \addtoindexx{abstract instance!example}
2113 OUTER.AI.3.1:
2114     \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
2115         \livelink{chap:DWATname}{DW\_AT\_name}("OUTER")
2116         \livelink{chap:DWATinline}{DW\_AT\_inline}(\livelink{chap:DWINLdeclaredinlined}{DW\_INL\_declared\_inlined})
2117         ! No low/high PCs
2118 OUTER.AI.3.2:
2119         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2120             \livelink{chap:DWATname}{DW\_AT\_name}("OUTER\_FORMAL")
2121             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
2122             ! No location
2123 OUTER.AI.3.3:
2124         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2125             \livelink{chap:DWATname}{DW\_AT\_name}("OUTER\_LOCAL")
2126             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
2127             ! No location
2128         !
2129         ! Normal INNER
2130         !
2131 OUTER.AI.3.4:
2132         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
2133             \livelink{chap:DWATname}{DW\_AT\_name}("INNER")
2134             \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}(...)
2135             \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}(...)
2136             \livelink{chap:DWATframebase}{DW\_AT\_frame\_base}(...)
2137             \livelink{chap:DWATstaticlink}{DW\_AT\_static\_link}(...)
2138 OUTER.AI.3.5:
2139             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2140                 \livelink{chap:DWATname}{DW\_AT\_name}("INNER\_FORMAL")
2141                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
2142                 \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2143 OUTER.AI.3.6:
2144             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2145                 \livelink{chap:DWATname}{DW\_AT\_name}("INNER\_LOCAL")
2146                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to integer)
2147                 \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2148             ...
2149             0
2150         ...
2151         0
2152 \end{alltt}
2153 \end{dwflisting}
2154 \caption{Inlining example \#3: abstract instance}
2155 \label{fig:inliningexample3abstractinstance}
2156 \end{figure}
2157
2158 \begin{figure}[t]
2159 \begin{dwflisting}
2160 \begin{alltt}
2161     ! Concrete instance for call "OUTER(7)"
2162     ! \addtoindexx{concrete instance!example}
2163 OUTER.CI.3.1:
2164     \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
2165         ! No name
2166         \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.3.1)
2167         \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}(...)
2168         \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}(...)
2169         \livelink{chap:DWATframebase}{DW\_AT\_frame\_base}(...)
2170 OUTER.CI.3.2:
2171         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2172             ! No name
2173             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.3.2)
2174             ! No type
2175             \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2176 OUTER.CI.3.3:
2177         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2178             ! No name
2179             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to OUTER.AI.3.3)
2180             ! No type
2181             \livelink{chap:DWATlocation}{DW\_AT\_location}(...)
2182         ! No \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram} for "INNER"
2183         ...
2184         0
2185 \end{alltt}
2186 \end{dwflisting}
2187 \caption{Inlining example \#3: concrete instance}
2188 \label{fig:inliningexample3concreteinstance}
2189 \end{figure}
2190
2191 \clearpage
2192 \section{Constant Expression Example}
2193 \label{app:constantexpressionexample}
2194 C++ generalizes the notion of constant expressions to include
2195 constant expression user-defined literals and functions.
2196 The constant declarations in Figure \refersec{fig:constantexpressionscsource}
2197 can be represented as illustrated in 
2198 Figure \refersec{fig:constantexpressionsdwarfdescription}.
2199
2200
2201 \begin{figure}[here]
2202 \begin{lstlisting}[numbers=none]
2203 constexpr double mass = 9.8;
2204 constexpr int square (int x) { return x * x; }
2205 float arr[square(9)]; // square() called and inlined
2206 \end{lstlisting}
2207 \caption{Constant expressions: C++ source} \label{fig:constantexpressionscsource}
2208 \end{figure}
2209
2210
2211 \begin{figure}[!h]
2212 \begin{dwflisting}
2213 \begin{alltt}
2214         ! For variable mass
2215         !
2216 1\$:     \livelink{chap:DWTAGconsttype}{DW\_TAG\_const\_type}
2217             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "double")
2218 2\$:     \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2219             \livelink{chap:DWATname}{DW\_AT\_name}("mass")
2220             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
2221             \livelink{chap:DWATconstexpr}{DW\_AT\_const\_expr}(true)
2222             \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}(9.8)
2223         ! Abstract instance for square
2224         !
2225 10\$:    \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
2226             \livelink{chap:DWATname}{DW\_AT\_name}("square")
2227             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2228             \livelink{chap:DWATinline}{DW\_AT\_inline}(\livelink{chap:DWINLinlined}{DW\_INL\_inlined})
2229 11\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2230                 \livelink{chap:DWATname}{DW\_AT\_name}("x")
2231                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2232         ! Concrete instance for square(9)
2233         ! \addtoindexx{concrete instance!example}
2234 20\$:    \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
2235             \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to 10\$)
2236             \livelink{chap:DWATconstexpr}{DW\_AT\_const\_expr}(present)
2237             \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}(81)
2238             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2239                 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}(reference to 11\$)
2240                 \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}(9)
2241         ! Anonymous array type for arr
2242         !
2243 30\$:    \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type}
2244             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "float")
2245             \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}(324) ! 81*4
2246             \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
2247                 \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2248                 \livelink{chap:DWATupperbound}{DW\_AT\_upper\_bound}(reference to 20\$)
2249         ! Variable arr
2250         !
2251 40\$:    \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2252             \livelink{chap:DWATname}{DW\_AT\_name}("arr")
2253             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 30\$)
2254 \end{alltt}
2255 \end{dwflisting}
2256 \caption{Constant expressions: DWARF description}
2257 \label{fig:constantexpressionsdwarfdescription}
2258 \end{figure}
2259
2260 \section{Unicode Character Example}
2261 \label{app:unicodecharacterexample}
2262 \addtoindexx{Unicode|see {\textit{also} UTF-8}}
2263 The \addtoindex{Unicode} character encodings in
2264 Figure \refersec{fig:unicodecharacterexamplesource}
2265 can be described in DWARF as illustrated in 
2266 Figure \refersec{fig:unicodecharacterexampledwarfdescription}.
2267
2268 \begin{figure}[!h]
2269 \begin{lstlisting}[numbers=none]
2270 // C++ source
2271 //
2272 char16_t chr_a = u'h';
2273 char32_t chr_b = U'h';
2274 \end{lstlisting}
2275 \caption{Unicode character example: source}
2276 \label{fig:unicodecharacterexamplesource}
2277 \end{figure}
2278
2279 \begin{figure}[h]
2280 \begin{dwflisting}
2281 \begin{alltt}
2282
2283 ! DWARF description
2284 !
2285 1\$: \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
2286         \livelink{chap:DWATname}{DW\_AT\_name}("char16\_t")
2287         \livelink{chap:DWATencoding}{DW\_AT\_encoding}(\livelink{chap:DWATEUTF}{DW\_ATE\_UTF})
2288         \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}(2)
2289 2\$: \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
2290         \livelink{chap:DWATname}{DW\_AT\_name}("char32\_t")
2291         \livelink{chap:DWATencoding}{DW\_AT\_encoding}(\livelink{chap:DWATEUTF}{DW\_ATE\_UTF})
2292         \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}(4)
2293 3\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2294         \livelink{chap:DWATname}{DW\_AT\_name}("chr\_a")
2295         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 1\$)
2296 4\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2297         \livelink{chap:DWATname}{DW\_AT\_name}("chr\_b")
2298         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 2\$)
2299 \end{alltt}
2300 \end{dwflisting}
2301 \caption{Unicode character example: DWARF description}
2302 \label{fig:unicodecharacterexampledwarfdescription}
2303 \end{figure}
2304
2305
2306 \section{Type-Safe Enumeration Example}
2307 \label{app:typesafeenumerationexample}
2308
2309 The \addtoindex{C++} type\dash safe enumerations in
2310 \addtoindexx{type-safe enumeration}
2311 Figure \refersec{fig:ctypesafeenumerationexamplesource}
2312 can be described in DWARF as illustrated in 
2313 Figure \refersec{fig:ctypesafeenumerationexampledwarf}.
2314
2315 \clearpage      % Get following source and DWARF on same page
2316
2317 \begin{figure}[H]
2318 \begin{lstlisting}[numbers=none]
2319 // C++ source
2320 //
2321 enum class E { E1, E2=100 };
2322 E e1;
2323 \end{lstlisting}
2324 \caption{Type-safe enumeration example: source}
2325 \label{fig:ctypesafeenumerationexamplesource}
2326 \end{figure}
2327
2328 \begin{figure}[H]
2329 \begin{dwflisting}
2330 \begin{alltt}
2331 ! DWARF description
2332 !
2333 11\$:  \livelink{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}
2334           \livelink{chap:DWATname}{DW\_AT\_name}("E")
2335           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2336           \livelink{chap:DWATenumclass}{DW\_AT\_enum\_class}(present)
2337 12\$:      \livelink{chap:DWTAGenumerator}{DW\_TAG\_enumerator}
2338               \livelink{chap:DWATname}{DW\_AT\_name}("E1")
2339               \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}(0)
2340 13\$:      \livelink{chap:DWTAGenumerator}{DW\_TAG\_enumerator}
2341               \livelink{chap:DWATname}{DW\_AT\_name}("E2")
2342               \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value}(100)
2343 14\$:  \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2344          \livelink{chap:DWATname}{DW\_AT\_name}("e1")
2345          \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 11\$)
2346 \end{alltt}
2347 \end{dwflisting}
2348 \caption{Type-safe enumeration example: DWARF description}
2349 \label{fig:ctypesafeenumerationexampledwarf}
2350 \end{figure}
2351
2352
2353 \clearpage
2354 \section{Template Examples}
2355 \label{app:templateexample}
2356
2357 The C++ template example in
2358 Figure \refersec{fig:ctemplateexample1source}
2359 can be described in DWARF as illustrated in 
2360 Figure \refersec{fig:ctemplateexample1dwarf}.
2361
2362 \begin{figure}[h]
2363 \begin{lstlisting}
2364 // C++ source
2365 //
2366 template<class T>
2367 struct wrapper {
2368     T comp;
2369 };
2370 wrapper<int> obj;
2371 \end{lstlisting}
2372 \caption{C++ template example \#1: source}
2373 \label{fig:ctemplateexample1source}
2374 \end{figure}
2375
2376 \begin{figure}[h]
2377 \begin{dwflisting}
2378 \begin{alltt}
2379 ! DWARF description
2380 !
2381 11\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2382         \livelink{chap:DWATname}{DW\_AT\_name}("wrapper")
2383 12\$:    \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2384             \livelink{chap:DWATname}{DW\_AT\_name}("T")
2385             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2386 13\$:    \livelink{chap:DWTAGmember}{DW\_TAG\_member}
2387             \livelink{chap:DWATname}{DW\_AT\_name}("comp")
2388             \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 12\$)
2389 14\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2390         \livelink{chap:DWATname}{DW\_AT\_name}("obj")
2391         \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 11\$)
2392 \end{alltt}
2393 \end{dwflisting}
2394 \caption{C++ template example \#1: DWARF description}
2395 \label{fig:ctemplateexample1dwarf}
2396 \end{figure}
2397
2398 The actual type of the component \texttt{comp} is \texttt{int}, but in the DWARF
2399 the type references the
2400 \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2401 for \texttt{T}, which in turn references \texttt{int}. This implies that in the
2402 original template comp was of type \texttt{T} and that was replaced
2403 with \texttt{int} in the instance. 
2404
2405 \needlines{10}
2406 There exist situations where it is
2407 not possible for the DWARF to imply anything about the nature
2408 of the original template. 
2409 Consider the C++ template source in
2410 Figure \refersec{fig:ctemplateexample2source}
2411 and the DWARF that can describe it in
2412 Figure \refersec{fig:ctemplateexample2dwarf}.
2413
2414 \begin{figure}[!h]
2415 \begin{lstlisting}
2416 // C++ source
2417 //
2418     template<class T>
2419     struct wrapper {
2420         T comp;
2421     };
2422     template<class U>
2423     void consume(wrapper<U> formal)
2424     {
2425         ...
2426     }
2427     wrapper<int> obj;
2428     consume(obj);
2429 \end{lstlisting}
2430 \caption{C++ template example \#2: source}
2431 \label{fig:ctemplateexample2source}
2432 \end{figure}
2433
2434 \begin{figure}[h]
2435 \begin{dwflisting}
2436 \begin{alltt}
2437 ! DWARF description
2438 !
2439 11\$:  \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2440           \livelink{chap:DWATname}{DW\_AT\_name}("wrapper")
2441 12\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2442               \livelink{chap:DWATname}{DW\_AT\_name}("T")
2443               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2444 13\$:      \livelink{chap:DWTAGmember}{DW\_TAG\_member}
2445               \livelink{chap:DWATname}{DW\_AT\_name}("comp")
2446               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 12\$)
2447 14\$:  \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2448           \livelink{chap:DWATname}{DW\_AT\_name}("obj")
2449           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 11\$)
2450 21\$:  \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
2451           \livelink{chap:DWATname}{DW\_AT\_name}("consume")
2452 22\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2453               \livelink{chap:DWATname}{DW\_AT\_name}("U")
2454               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2455 23\$:      \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
2456               \livelink{chap:DWATname}{DW\_AT\_name}("formal")
2457               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 11\$)
2458 \end{alltt}
2459 \end{dwflisting}
2460 \caption{C++ template example \#2: DWARF description}
2461 \label{fig:ctemplateexample2dwarf}
2462 \end{figure}
2463
2464 In the \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram} 
2465 entry for the instance of consume, \texttt{U} is described as \texttt{int}. 
2466 The type of formal is \texttt{wrapper\textless U\textgreater} in
2467 the source. DWARF only represents instantiations of templates;
2468 there is no entry which represents \texttt{wrapper\textless U\textgreater} 
2469 which is neither
2470 a template parameter nor a template instantiation. The type
2471 of formal is described as \texttt{wrapper\textless int\textgreater},
2472 the instantiation of \texttt{wrapper\textless U\textgreater},
2473 in the \livelink{chap:DWATtype}{DW\_AT\_type} attribute at 
2474 23\$. 
2475 There is no
2476 description of the relationship between template type parameter
2477 \texttt{T} at 12\$ and \texttt{U} at 22\$ which was used to instantiate
2478 \texttt{wrapper\textless U\textgreater}.
2479
2480 A consequence of this is that the DWARF information would
2481 not distinguish between the existing example and one where
2482 the formal parameter of \texttt{consume} were declared in the source to be
2483 \texttt{wrapper\textless int\textgreater}.
2484
2485
2486 \section{Template Alias Examples}
2487 \label{app:templatealiasexample}
2488
2489 The \addtoindex{C++} template alias shown in
2490 Figure \refersec{fig:ctemplatealiasexample1source}
2491 can be described in DWARF as illustrated 
2492 \addtoindexx{template alias example} in 
2493 Figure \refersec{fig:ctemplatealiasexample1dwarf}.
2494
2495 \begin{figure}[h]
2496 \begin{lstlisting}
2497 // C++ source, template alias example 1
2498 //
2499 template<typename T, typename U>
2500 struct Alpha {
2501     T tango;
2502     U uniform;
2503 };
2504 template<typename V> using Beta = Alpha<V,V>;
2505 Beta<long> b;
2506 \end{lstlisting}
2507 \caption{C++ template alias example \#1: source}
2508 \label{fig:ctemplatealiasexample1source}
2509 \end{figure}
2510
2511 \begin{figure}[h]
2512 \addtoindexx{template alias example 1}
2513 \begin{dwflisting}
2514 \begin{alltt}
2515 ! DWARF representation for variable 'b'
2516 !
2517 20\$:  \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2518           \livelink{chap:DWATname}{DW\_AT\_name}("Alpha")
2519 21\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2520               \livelink{chap:DWATname}{DW\_AT\_name}("T")
2521               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "long")
2522 22\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2523               \livelink{chap:DWATname}{DW\_AT\_name}("U")
2524               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "long")
2525 23\$:      \livelink{chap:DWTAGmember}{DW\_TAG\_member}
2526               \livelink{chap:DWATname}{DW\_AT\_name}("tango")
2527               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 21\$)
2528 24\$:      \livelink{chap:DWTAGmember}{DW\_TAG\_member}
2529               \livelink{chap:DWATname}{DW\_AT\_name}("uniform")
2530               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 22\$)
2531 25\$:  \livelink{chap:DWTAGtemplatealias}{DW\_TAG\_template\_alias}
2532           \livelink{chap:DWATname}{DW\_AT\_name}("Beta")
2533           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 20\$)
2534 26\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2535               \livelink{chap:DWATname}{DW\_AT\_name}("V")
2536               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "long")
2537 27\$:  \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2538           \livelink{chap:DWATname}{DW\_AT\_name}("b")
2539           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 25\$)
2540 \end{alltt}
2541 \end{dwflisting}
2542 \caption{C++ template alias example \#1: DWARF description}
2543 \label{fig:ctemplatealiasexample1dwarf}
2544 \end{figure}
2545
2546 Similarly, the \addtoindex{C++} template alias shown in
2547 Figure \refersec{fig:ctemplatealiasexample2source}
2548 can be described in DWARF as illustrated 
2549 \addtoindexx{template alias example} in 
2550 Figure \refersec{fig:ctemplatealiasexample2dwarf}.
2551
2552 \begin{figure}[h]
2553 \begin{lstlisting}
2554 // C++ source, template alias example 2
2555 //
2556 template<class TX> struct X { };
2557 template<class TY> struct Y { };
2558 template<class T> using Z = Y<T>;
2559 X<Y<int>> y;
2560 X<Z<int>> z;
2561 \end{lstlisting}
2562 \caption{C++ template alias example \#2: source}
2563 \label{fig:ctemplatealiasexample2source}
2564 \end{figure}
2565
2566 \begin{figure}[h]
2567 \addtoindexx{template alias example 2}
2568 \begin{dwflisting}
2569 \begin{alltt}
2570 ! DWARF representation for X<Y<int>>
2571 !
2572 30\$:  \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2573           \livelink{chap:DWATname}{DW\_AT\_name}("Y")
2574 31\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2575               \livelink{chap:DWATname}{DW\_AT\_name}("TY")
2576               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2577 32\$:  \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2578           \livelink{chap:DWATname}{DW\_AT\_name}("X")
2579 33\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2580               \livelink{chap:DWATname}{DW\_AT\_name}("TX")
2581               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 30\$)
2582 !
2583 ! DWARF representation for X<Z<int>>
2584 !
2585 40\$:  \livelink{chap:DWTAGtemplatealias}{DW\_TAG\_template\_alias}
2586           \livelink{chap:DWATname}{DW\_AT\_name}("Z")
2587           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 30\$)
2588 41\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2589               \livelink{chap:DWATname}{DW\_AT\_name}("T")
2590               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to "int")
2591 42\$:  \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2592           \livelink{chap:DWATname}{DW\_AT\_name}("X")
2593 43\$:      \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2594               \livelink{chap:DWATname}{DW\_AT\_name}("TX")
2595               \livelink{chap:DWATtype}{DW\_AT\_type}(reference to 40\$)
2596 !
2597 ! Note that 32\$ and 42\$ are actually the same type
2598 !
2599 50\$:  \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2600           \livelink{chap:DWATname}{DW\_AT\_name}("y")
2601           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to \$32)
2602 51\$:  \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2603           \livelink{chap:DWATname}{DW\_AT\_name}("z")
2604           \livelink{chap:DWATtype}{DW\_AT\_type}(reference to \$42)
2605 \end{alltt}
2606 \end{dwflisting}
2607 \caption{C++ template alias example \#2: DWARF description}
2608 \label{fig:ctemplatealiasexample2dwarf}
2609 \end{figure}