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