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