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