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