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