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