a39e99adcbc684f4394821d7f66d5ed6b1204c48
[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 DW\_AT\_name       DW\_FORM\_string
111 DW\_AT\_producer   DW\_FORM\_string
112 DW\_AT\_comp\_dir   DW\_FORM\_string
113 DW\_AT\_language   DW\_FORM\_data1
114 DW\_AT\_low\_pc     DW\_FORM\_addr
115 DW\_AT\_high\_pc    DW\_FORM\_data1
116 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 DW\_AT\_name       DW\_FORM\_string
124 DW\_AT\_encoding   DW\_FORM\_data1
125 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 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 DW\_AT\_name      DW\_FORM\_string
140 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 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 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 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         DW\_AT\_type(reference to REAL)
291         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         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         DW\_AT\_type(reference to INTEGER)
306         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         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         DW\_AT\_name("array\_ptr")
330         DW\_AT\_byte\_size(constant sizeof(REAL) + sizeof(desc<1>))
331 4\$:     \livelink{chap:DWTAGmember}{DW\_TAG\_member}
332             DW\_AT\_name("myvar")
333             DW\_AT\_type(reference to REAL)
334             DW\_AT\_data\_member\_location(constant 0)
335 5\$:     \livelink{chap:DWTAGmember}{DW\_TAG\_member}
336             DW\_AT\_name("ap");
337             DW\_AT\_type(reference to 1\$)
338             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         DW\_AT\_type(reference to 3\$)
343         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         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         DW\_AT\_type(reference to INTEGER)
361         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         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         DW\_AT\_name("arrays")
374         DW\_AT\_type(reference to 6\$)
375         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 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 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 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 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 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         DW\_AT\_name("M")
559         DW\_AT\_type(reference to INTEGER)
560 12\$: \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type}
561         ! No name, default (Ada) order, default stride
562         DW\_AT\_type(reference to INTEGER)
563 13\$:    \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
564             DW\_AT\_type(reference to INTEGER)
565             DW\_AT\_lower\_bound(constant 1)
566             DW\_AT\_upper\_bound(reference to variable M at 11\$)
567 14\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
568         DW\_AT\_name("VEC1")
569         DW\_AT\_type(reference to array type at 12\$)
570     . . .
571 21\$: \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
572         DW\_AT\_name("TEENY")
573         DW\_AT\_type(reference to INTEGER)
574         DW\_AT\_lower\_bound(constant 1)
575         DW\_AT\_upper\_bound(constant 100)
576
577       . . .
578 26\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
579         DW\_AT\_name("REC2")
580 27\$:   \livelink{chap:DWTAGmember}{DW\_TAG\_member}
581             DW\_AT\_name("N")
582             DW\_AT\_type(reference to subtype TEENY at 21\$)
583             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             DW\_AT\_TYPE(reference to INTEGER)
588 29\$:       \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
589                 DW\_AT\_type(reference to subrange TEENY at 21\$)
590                 DW\_AT\_lower\_bound(constant 1)
591                 DW\_AT\_upper\_bound(reference to member N at 27\$)
592 30\$:   \livelink{chap:DWTAGmember}{DW\_TAG\_member}
593             DW\_AT\_name("VEC2")
594             DW\_AT\_type(reference to array “subtype” at 28\$)
595             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         DW\_AT\_name("OBJ2B")
601         DW\_AT\_type(reference to REC2 at 26\$)
602         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 \begin{alltt}
647
648 21\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type} ! anonymous type for F2
649         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
650             DW\_AT\_name("F3")
651             DW\_AT\_type(reference to 11\$)
652 22\$: \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type} ! anonymous type for F4
653         DW\_AT\_type(reference to 20\$)
654         \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
655             DW\_AT\_type(reference to 11\$)
656             DW\_AT\_lower\_bound(0)
657             DW\_AT\_upper\_bound(1)
658         DW\_AT\_bit\_stride(2)
659         DW\_AT\_bit\_size(4)
660 23\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type} ! anonymous type for V
661         DW\_AT\_bit\_size(39)
662         \livelink{chap:DWTAGmember}{DW\_TAG\_member}
663             DW\_AT\_name("F1")
664             DW\_AT\_type(reference to 10\$)
665             DW\_AT\_data\_bit\_offset(0)! may be omitted
666             DW\_AT\_bit\_size(1) ! may be omitted
667         DW\_AT\_member
668             DW\_AT\_name("F2")
669             DW\_AT\_type(reference to 21\$)
670             DW\_AT\_data\_bit\_offset(1)
671             DW\_AT\_bit\_size(32) ! may be omitted
672         DW\_AT\_member
673             DW\_AT\_name("F4")
674             DW\_AT\_type(reference to 22\$)
675             DW\_AT\_data\_bit\_offset(33)
676             DW\_AT\_bit\_size(4) ! may be omitted
677         DW\_AT\_member
678             DW\_AT\_name("F7")
679             DW\_AT\_type(reference to 20\$) ! type T
680             DW\_AT\_data\_bit\_offset(37)
681             DW\_AT\_bit\_size(2) ! may be omitted
682      \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
683         DW\_AT\_name("V")
684         DW\_AT\_type(reference to 23\$)
685         DW\_AT\_location(...)
686         ...
687 \end{alltt}
688
689 \section{Namespace Example}
690 \label{app:namespaceexample}
691
692
693 The C++ example in 
694 Figure \refersec{fig:namespaceexamplesourcefragment}
695 is used to illustrate the representation of namespaces.
696
697 \begin{figure}[here]
698 \begin{lstlisting}
699 namespace {
700     int i;
701 }
702
703 namespace A {
704     namespace B {
705         int j;
706         int myfunc (int a);
707         float myfunc (float f) { return f – 2.0; }
708         int myfunc2(int a) { return a + 2; }
709     }
710 }
711 namespace Y {
712     using A::B::j;         // (1) using declaration
713     int foo;
714 }
715
716 using A::B::j;             // (2) using declaration
717 namespace Foo = A::B;      // (3) namespace alias
718 using Foo::myfunc;         // (4) using declaration
719 using namespace Foo;       // (5) using directive
720 namespace A {
721     namespace B {
722         using namespace Y; // (6) using directive
723         int k;
724     }
725 }
726 int Foo::myfunc(int a)
727 {
728     i = 3;
729     j = 4;
730     return myfunc2(3) + j + i + a + 2;
731 }
732 \end{lstlisting}
733 \caption{Namespace example: source fragment} \label{fig:namespaceexamplesourcefragment}
734 \end{figure}
735
736
737 The DWARF representation in 
738 Section \refersec{app:namespaceexampledwarfdescription}
739 is appropriate.
740
741 \subsection{Namespace example: DWARF description}
742 \label{app:namespaceexampledwarfdescription}
743 \begin{alltt}
744
745 1\$:  \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
746         DW\_AT\_name("int")
747         ...
748 2\$:  \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
749         DW\_AT\_name("float")
750         ...
751 6\$:  \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
752         ! no DW\_AT\_name attribute
753 7\$:
754         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
755             DW\_AT\_name("i")
756             DW\_AT\_type(reference to 1\$)
757             DW\_AT\_location ...
758             ...
759 10\$: \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
760         DW\_AT\_name("A")
761 20\$:    \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
762             DW\_AT\_name("B")
763 30\$:        \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
764                 DW\_AT\_name("j")
765                 DW\_AT\_type(reference to 1\$)
766                 DW\_AT\_location ...
767                 ...
768 34\$:        \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
769                 DW\_AT\_name("myfunc")
770                 DW\_AT\_type(reference to 1\$)
771                 ...
772 36\$:        \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
773                 DW\_AT\_name("myfunc")
774                 DW\_AT\_type(reference to 2\$)
775                 ...
776 38\$:        \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
777                 DW\_AT\_name("myfunc2")
778                 DW\_AT\_low\_pc ...
779                 DW\_AT\_high\_pc ...
780                 DW\_AT\_type(reference to 1\$)
781                 ...
782
783 40\$: \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
784         DW\_AT\_name("Y")
785         \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}    ! (1) using-declaration
786             DW\_AT\_import(reference to 30\$)
787         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
788             DW\_AT\_name("foo")
789             DW\_AT\_type(reference to 1\$)
790             DW\_AT\_location ...
791             ...
792      \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}       ! (2) using declaration
793         DW\_AT\_import(reference to 30\$)
794         \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}    ! (3) namespace alias
795             DW\_AT\_name("Foo")
796             DW\_AT\_import(reference to 20\$)
797         \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}    ! (4) using declaration
798             DW\_AT\_import(reference to 34\$) ! - part 1
799         \livelink{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}    ! (4) using declaration
800             DW\_AT\_import(reference to 36\$) !  - part 2
801         \livelink{chap:DWTAGimportedmodule}{DW\_TAG\_imported\_module}         ! (5) using directive
802             DW\_AT\_import(reference to 20\$)
803         \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
804             DW\_AT\_extension(reference to 10\$)
805             \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
806                 DW\_AT\_extension(reference to 20\$)
807                 \livelink{chap:DWTAGimportedmodule}{DW\_TAG\_imported\_module} ! (6) using directive
808                     DW\_AT\_import(reference to 40\$)
809                 \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
810                     DW\_AT\_name("k")
811                     DW\_AT\_type(reference to 1\$)
812                     DW\_AT\_location ...
813                     ...
814 60\$: \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
815         DW\_AT\_specification(reference to 34\$)
816         DW\_AT\_low\_pc ...
817         DW\_AT\_high\_pc ...
818         ...
819 \end{alltt}
820
821 \section{Member Function Example}
822 \label{app:memberfunctionexample}
823
824 Consider the member function example fragment in 
825 Figure \refersec{fig:memberfunctionexamplesourcefragment}.
826
827 \begin{figure}[here]
828 \begin{lstlisting}
829 class A
830 {
831     void func1(int x1);
832     void func2() const;
833     static void func3(int x3);
834 };
835 void A::func1(int x) {}
836 \end{lstlisting}
837 \caption{Member function example: source fragment} \label{fig:memberfunctionexamplesourcefragment}
838 \end{figure}
839
840
841
842 The DWARF representation in 
843 Section \refersec{app:memberfunctionexampledwarfdescription}
844 is appropriate.
845
846 \subsection{Member function example: DWARF description}
847 \label{app:memberfunctionexampledwarfdescription}
848
849
850 \begin{alltt}
851 1\$: \livelink{chap:DWTAGunspecifiedtype}{DW\_TAG\_unspecified\_type}
852         DW\_AT\_name("void")
853                 ...
854 2\$ \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
855         DW\_AT\_name("int")
856         ...
857 3\$: \livelink{chap:DWTAGclasstype}{DW\_TAG\_class\_type}
858         DW\_AT\_name("A")
859         ...
860 4\$:    \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type}
861             DW\_AT\_type(reference to 3\$)
862             ...
863 5\$:    \livelink{chap:DWTAGconsttype}{DW\_TAG\_const\_type}
864             DW\_AT\_type(reference to 3\$)
865             ...
866 6\$:    \livelink{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type}
867             DW\_AT\_type(reference to 5\$)
868             ...
869
870 7\$:    \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
871             DW\_AT\_declaration
872             DW\_AT\_name("func1")
873             DW\_AT\_type(reference to 1\$)
874             DW\_AT\_object\_pointer(reference to 8\$)
875                 ! References a formal parameter in this 
876                 ! member function
877             ...
878 8\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
879                 DW\_AT\_artificial(true)
880                 DW\_AT\_name("this")
881                 DW\_AT\_type(reference to 4\$)
882                     ! Makes type of 'this' as 'A*' =>
883                     ! func1 has not been marked const 
884                     ! or volatile
885                 DW\_AT\_location ...
886                 ...
887 9\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
888                 DW\_AT\_name(x1)
889                 DW\_AT\_type(reference to 2\$)
890                 ...
891 10\$:    \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
892              DW\_AT\_declaration
893              DW\_AT\_name("func2")
894              DW\_AT\_type(reference to 1\$)
895              DW\_AT\_object\_pointer(reference to 11\$)
896              ! References a formal parameter in this 
897              ! member function
898              ...
899 11\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
900                  DW\_AT\_artificial(true)
901                  DW\_AT\_name("this")
902                  DW\_AT\_type(reference to 6\$)
903                      ! Makes type of 'this' as 'A const*' =>
904                  !     func2 marked as const
905                  DW\_AT\_location ...
906                  ...
907 12\$:    \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
908              DW\_AT\_declaration
909              DW\_AT\_name("func3")
910              DW\_AT\_type(reference to 1\$)
911              ...
912                  ! No object pointer reference formal parameter
913                  ! implies func3 is static
914 13\$:        \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
915                  DW\_AT\_name(x3)
916                  DW\_AT\_type(reference to 2\$)
917                  ...
918 \end{alltt}
919
920 \section{Line Number Program Example}
921 \label{app:linenumberprogramexample}
922
923 Consider the simple source file and the resulting machine
924 code for the Intel 8086 processor in 
925 Figure \refersec{fig:linenumberprogramexamplemachinecode}.
926
927 \begin{figure}[here]
928 \begin{lstlisting}
929 1: int
930 2: main()
931     0x239: push pb
932     0x23a: mov bp,sp
933 3: {
934 4: printf("Omit needless words\n");
935     0x23c: mov ax,0xaa
936     0x23f: push ax
937     0x240: call _printf
938     0x243: pop cx
939 5: exit(0);
940     0x244: xor ax,ax
941     0x246: push ax
942     0x247: call _exit
943     0x24a: pop cx
944 6: }
945     0x24b: pop bp
946     0x24c: ret
947 7: 0x24d:
948 \end{lstlisting}
949 \caption{Line number program example: machine code} \label{fig:linenumberprogramexamplemachinecode}
950 \end{figure}
951
952 Suppose the line number program header includes the following
953 (header fields not needed below are not shown):
954
955
956
957 \begin{alltt}
958 version                    4
959 minimum_instruction_length 1
960 opcode_base               10 ! Opcodes 10-12 not needed
961 line_base                  1
962 line_range                15
963 \end{alltt}
964
965
966 Figure \refersec{tab:linenumberprogramexampleoneencoding}
967 shows one encoding of the line number program, which occupies
968 12 bytes (the opcode SPECIAL(m,n) indicates the special opcode
969 generated for a line increment of m and an address increment
970 of n).
971
972
973 \begin{centering}
974 \setlength{\extrarowheight}{0.1cm}
975 \begin{longtable}{lll}
976   \caption{Line number program example: one encoding} \label{tab:linenumberprogramexampleoneencoding} \\
977   \hline \\ \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
978 \endfirsthead
979   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
980 \endhead
981   \hline \emph{Continued on next page}
982 \endfoot
983   \hline
984 \endlastfoot
985 DW\_LNS\_advance\_pc&LEB128(0x239)&0x2, 0xb9, 0x04 \\
986 SPECIAL(2, 0)&0xb  & \\
987 SPECIAL(2, 3)&0x38 & \\
988 SPECIAL(1, 8)&0x82 & \\
989 SPECIAL(1, 7)&0x73 & \\
990 DW\_LNS\_advance\_pc&LEB128(2)&0x2, 0x2 \\
991 DW\_LNE\_end\_sequence &&0x0, 0x1, 0x1 \\
992 \end{longtable}
993 \end{centering}
994
995
996 Table \refersec{tab:linenumberprogramexamplealternateencoding}
997 shows an alternate 
998 encoding of the same program using 
999 standard opcodes to advance
1000 the program counter; 
1001 this encoding occupies 22 bytes.
1002
1003 \begin{centering}
1004 \setlength{\extrarowheight}{0.1cm}
1005 \begin{longtable}{lll}
1006   \caption{Line number program example: alternate encoding} \label{tab:linenumberprogramexamplealternateencoding} \\
1007   \hline \\ \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
1008 \endfirsthead
1009   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
1010 \endhead
1011   \hline \emph{Continued on next page}
1012 \endfoot
1013   \hline
1014 \endlastfoot
1015 DW\_LNS\_fixed\_advance\_pc&0x239&0x9, 0x39, 0x2        \\
1016 SPECIAL(2, 0)&& 0xb        \\
1017 DW\_LNS\_fixed\_advance\_pc&0x3&0x9, 0x3, 0x0        \\
1018 SPECIAL(2, 0)&&0xb        \\
1019 DW\_LNS\_fixed\_advance\_pc&0x8&0x9, 0x8, 0x0        \\
1020 SPECIAL(1, 0)&& 0xa        \\
1021 DW\_LNS\_fixed\_advance\_pc&0x7&0x9, 0x7, 0x0        \\
1022 SPECIAL(1, 0) && 0xa        \\
1023 DW\_LNS\_fixed\_advance\_pc&0x2&0x9, 0x2, 0x0        \\
1024 DW\_LNE\_end\_sequence&&0x0, 0x1, 0x1        \\
1025 \end{longtable}
1026 \end{centering}
1027
1028
1029 \section{Call Frame Information Example}
1030 \label{app:callframeinformationexample}
1031
1032 The following example uses a hypothetical RISC machine in
1033 the style of the Motorola 88000.
1034
1035 \begin{itemize}
1036 \item Memory is byte addressed.
1037
1038 \item Instructions are all 4 bytes each and word aligned.
1039
1040 \item Instruction operands are typically of the form:
1041
1042 \begin{alltt}
1043 <destination.reg>, <source.reg>, <constant>
1044 \end{alltt}
1045
1046 \item The address for the load and store instructions is computed
1047 by adding the contents of the
1048 source register with the constant.
1049
1050 \item There are 8 4\dash byte registers:
1051
1052 \begin{alltt}
1053 R0 always 0
1054 R1 holds return address on call
1055 R2-R3 temp registers (not preserved on call)
1056 R4-R6 preserved on call
1057 R7 stack pointer.
1058 \end{alltt}
1059
1060 \item  The stack grows in the negative direction.
1061
1062 \item The architectural ABI committee specifies that the
1063 stack pointer (R7) is the same as the CFA
1064
1065 \end{itemize}
1066
1067 The following 
1068 (Figure refersec{fig:callframeinformationexamplemachinecodefragments}
1069 are two code fragments from a subroutine called
1070 foo that uses a frame pointer (in addition to the stack
1071 pointer). The first column values are byte addresses. 
1072 % The \space is so we get a space after >
1073 \textless~fs~\textgreater \  denotes the stack frame size in bytes, namely 12.
1074
1075
1076 \begin{figure}[here]
1077 \begin{lstlisting}
1078        ;; start prologue
1079 foo    sub R7, R7, <fs>        ; Allocate frame
1080 foo+4  store R1, R7, (<fs>-4)  ; Save the return address
1081 foo+8  store R6, R7, (<fs>-8)  ; Save R6
1082 foo+12 add R6, R7, 0           ; R6 is now the Frame ptr
1083 foo+16 store R4, R6, (<fs>-12) ; Save a preserved reg
1084        ;; This subroutine does not change R5
1085        ...
1086        ;; Start epilogue (R7 is returned to entry value)
1087 foo+64 load R4, R6, (<fs>-12)  ; Restore R4
1088 foo+68 load R6, R7, (<fs>-8)   ; Restore R6
1089 foo+72 load R1, R7, (<fs>-4)   ; Restore return address
1090 foo+76 add R7, R7, <fs>        ; Deallocate frame
1091 foo+80 jump R1 ; Return
1092 foo+84
1093 \end{lstlisting}
1094 \caption{Call frame information example: machine code fragments} \label{fig:callframeinformationexamplemachinecodefragments}
1095 \end{figure}
1096
1097
1098 An abstract table 
1099 (see Section \refersec{chap:structureofcallframeinformation}) 
1100 for the foo subroutine
1101 is shown in 
1102 Table \refersec{tab:callframeinformationexampleconceptualmatrix}.
1103 Corresponding fragments from the
1104 .debug\_frame section are shown in 
1105 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
1106
1107 The following notations apply in 
1108 Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
1109
1110 \begin{alltt}
1111 1. R8 is the return address
1112 2. s = same\_value rule
1113 3. u = undefined rule
1114 4. rN = register(N) rule
1115 5. cN = offset(N) rule
1116 6. a = architectural rule
1117 \end{alltt}
1118
1119 \begin{centering}
1120 \setlength{\extrarowheight}{0.1cm}
1121 \begin{longtable}{lllllllllll}
1122   \caption{Call frame inforation example: conceptual matrix} \label{tab:callframeinformationexampleconceptualmatrix} \\
1123   \hline \\ \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
1124 \endfirsthead
1125   \bfseries Location &\bfseries CFA &\bfseries R0 & \bfseries R1 & \bfseries R2 &\bfseries R3 &\bfseries R4 &\bfseries R5 &\bfseries R6 &\bfseries R7 &\bfseries R8\\ \hline
1126 \endhead
1127   \hline \emph{Continued on next page}
1128 \endfoot
1129   \hline
1130 \endlastfoot
1131 foo&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
1132 foo+4&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
1133 foo+8&[R7]+fs&s&u&u&u&s&s&s&a&c-4 \\
1134 foo+12&[R7]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
1135 foo+16&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
1136 foo+20&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
1137 ...&&&&&&&&&& \\
1138 foo+64&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
1139 foo+68&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4  \\
1140 foo+72&[R7]+fs&s&u&u&u&s&s&s&a&c-4  \\
1141 foo+76&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
1142 foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
1143 \end{longtable}
1144 \end{centering}
1145
1146
1147 \begin{centering}
1148 \setlength{\extrarowheight}{0.1cm}
1149 \begin{longtable}{lll}
1150   \caption{Call frame information example: common information entry encoding} \label{tab:callframeinformationexamplecommoninformationentryencoding} \\
1151   \hline \\ \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1152 \endfirsthead
1153   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1154 \endhead
1155   \hline \emph{Continued on next page}
1156 \endfoot
1157   \hline
1158 \endlastfoot
1159 cie&36&length    \\
1160 cie+4&0xffffffff&CIE\_id    \\
1161 cie+8&4&version    \\
1162 cie+9&0&augmentation     \\
1163 cie+10&4&address size    \\
1164 cie+11&0&segment size    \\
1165 cie+12&4&code\_alignment\_factor, \textless caf \textgreater    \\
1166 cie+13&-4&data\_alignment\_factor, \textless daf \textgreater    \\
1167 cie+14&8&R8 is the return addr.    \\
1168 cie+15&DW\_CFA\_def\_cfa (7, 0)&CFA = [R7]+0    \\
1169 cie+18&DW\_CFA\_same\_value (0)&R0 not modified (=0)    \\
1170 cie+20&DW\_CFA\_undefined (1)&R1 scratch    \\
1171 cie+22&DW\_CFA\_undefined (2)&R2 scratch    \\
1172 cie+24&DW\_CFA\_undefined (3)&R3 scratch    \\
1173 cie+26&DW\_CFA\_same\_value (4)&R4 preserve    \\
1174 cie+28&DW\_CFA\_same\_value (5)&R5 preserve    \\
1175 cie+30&DW\_CFA\_same\_value (6)&R6 preserve    \\
1176 cie+32&DW\_CFA\_same\_value (7)&R7 preserve    \\
1177 cie+34&DW\_CFA\_register (8, 1)&R8 is in R1    \\
1178 cie+37&DW\_CFA\_nop&padding    \\
1179 cie+38&DW\_CFA\_nop& padding \\
1180 cie+39& DW\_CFA\_nop&padding  \\
1181 cie+40 &&  \\
1182 \end{longtable}
1183 \end{centering}
1184
1185
1186 The following notations apply in 
1187 Table \refersec{tab:callframeinformationexampleframedescriptionentryencoding}:
1188
1189 \begin{alltt}
1190 1. <fs> = frame size
1191 2. <caf> = code alignment factor
1192 3. <daf> = data alignment factor
1193 \end{alltt}
1194
1195
1196 \begin{centering}
1197 \setlength{\extrarowheight}{0.1cm}
1198 \begin{longtable}{lll}
1199   \caption{Call frame information example: frame description entry encoding} \label{tab:callframeinformationexampleframedescriptionentryencoding} \\
1200   \hline \\ \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1201 \endfirsthead
1202   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1203 \endhead
1204   \hline \emph{Continued on next page}
1205 \endfoot
1206   \hline
1207 \endlastfoot
1208 fde&40&length \\
1209 fde+4&cie&CIE\_ptr \\
1210 fde+8&foo&initial\_location \\
1211 fde+12&84&address\_range \\
1212 fde+16&DW\_CFA\_advance\_loc(1)&instructions \\
1213 fde+17&DW\_CFA\_def\_cfa\_offset(12)& \textless fs \textgreater \\
1214 fde+19&DW\_CFA\_advance\_loc(1)&4/ \textless caf \textgreater \\
1215 fde+20&DW\_CFA\_offset(8,1)&-4/ \textless daf \textgreater (second parameter) \\
1216 fde+22&DW\_CFA\_advance\_loc(1)& \\
1217 fde+23&DW\_CFA\_offset(6,2)&-8/ \textless daf> \textgreater (2nd parameter)  \\
1218 fde+25&DW\_CFA\_advance\_loc(1) & \\
1219 fde+26&DW\_CFA\_def\_cfa\_register(6) & \\
1220 fde+28&DW\_CFA\_advance\_loc(1) & \\
1221 fde+29&DW\_CFA\_offset(4,3)&-12/ \textless daf \textgreater (2nd parameter) \\
1222 fde+31&DW\_CFA\_advance\_loc(12)&44/ \textless caf \textgreater \\
1223 fde+32&DW\_CFA\_restore(4)& \\
1224 fde+33&DW\_CFA\_advance\_loc(1) & \\
1225 fde+34&DW\_CFA\_restore(6) & \\
1226 fde+35&DW\_CFA\_def\_cfa\_register(7)  & \\
1227 fde+37&DW\_CFA\_advance\_loc(1) & \\
1228 fde+38&DW\_CFA\_restore(8) &\\
1229 fde+39&DW\_CFA\_advance\_loc(1) &\\
1230 fde+40&DW\_CFA\_def\_cfa\_offset(0)  &\\
1231 fde+42&DW\_CFA\_nop&padding \\
1232 fde+43&DW\_CFA\_nop&padding \\
1233 fde+44 && \\
1234 \end{longtable}
1235 \end{centering}
1236
1237 \section{Inlining Examples}
1238 \label{app:inliningexamples}
1239 The pseudo\dash source in 
1240 Figure \refersec{fig:inliningexamplespseudosourcefragment}
1241 is used to illustrate the
1242 use of DWARF to describe inlined subroutine calls. This
1243 example involves a nested subprogram INNER that makes uplevel
1244 references to the formal parameter and local variable of the
1245 containing subprogram OUTER.
1246
1247 \begin{figure}[here]
1248 \begin{lstlisting}
1249 inline procedure OUTER (OUTER_FORMAL : integer) =
1250     begin
1251     OUTER_LOCAL : integer;
1252     procedure INNER (INNER_FORMAL : integer) =
1253         begin
1254         INNER_LOCAL : integer;
1255         print(INNER_FORMAL + OUTER_LOCAL);
1256         end;
1257     INNER(OUTER_LOCAL);
1258     ...
1259     INNER(31);
1260     end;
1261 ! Call OUTER
1262 !
1263 OUTER(7);
1264 \end{lstlisting}
1265 \caption{Inlining examples: pseudo-source fragmment} \label{fig:inliningexamplespseudosourcefragment}
1266 \end{figure}
1267
1268
1269 There are several approaches that a compiler might take to
1270 inlining for this sort of example. This presentation considers
1271 three such approaches, all of which involve inline expansion
1272 of subprogram OUTER. (If OUTER is not inlined, the inlining
1273 reduces to a simpler single level subset of the two level
1274 approaches considered here.)
1275
1276 The approaches are:
1277
1278 \begin{itemize}[1.]
1279 \item  Inline both OUTER and INNER in all cases
1280
1281 \item Inline OUTER, multiple INNERs \\
1282 Treat INNER as a non\dash inlinable part of OUTER, compile and
1283 call a distinct normal version of INNER defined within each
1284 inlining of OUTER.
1285
1286 \item Inline OUTER, one INNER \\
1287 Compile INNER as a single normal subprogram which is called
1288 from every inlining of OUTER.
1289 \end{itemize}
1290
1291 This discussion does not consider why a compiler might choose
1292 one of these approaches; it considers only how to describe
1293 the result.
1294
1295 In the examples that follow in this section, the debugging
1296 information entries are given mnemonic labels of the following
1297 form
1298
1299 \begin{lstlisting}
1300 <io>.<ac>.<n>.<s>
1301 \end{lstlisting}
1302
1303 where \begin{verbatim}<io>\end{verbatim}
1304 is either INNER or OUTER to indicate to which
1305 subprogram the debugging information entry applies, 
1306 \begin{verbatim}<ac>\end{verbatim}
1307 is either AI or CI to indicate ``abstract instance'' or
1308 ``concrete instance'' respectively, 
1309 \begin{verbatim}<n>\end{verbatim}
1310 is the number of the
1311 alternative being considered, and 
1312 \begin{verbatim}<s>\end{verbatim}
1313 is a sequence number that
1314 distinguishes the individual entries. There is no implication
1315 that symbolic labels, nor any particular naming convention,
1316 are required in actual use.
1317
1318 For conciseness, declaration coordinates and call coordinates are omitted.
1319
1320 \subsection{Alternative 1: inline both OUTER and INNER}
1321 \label{app:inlinebothouterandinner}
1322
1323 A suitable abstract instance for an alternative where both
1324 OUTER and INNER are always inlined is shown in 
1325 Figure \refersec{app:inliningexample1abstractinstance}
1326
1327 Notice in 
1328 Section \refersec{app:inliningexample1abstractinstance} 
1329 that the debugging information entry for
1330 INNER (labelled INNER.AI.1.1) is nested in (is a child of)
1331 that for OUTER (labelled OUTER.AI.1.1). Nonetheless, the
1332 abstract instance tree for INNER is considered to be separate
1333 and distinct from that for OUTER.
1334
1335 The call of OUTER shown in 
1336 Figure \refersec{fig:inliningexamplespseudosourcefragment}
1337 might be described as
1338 shown in 
1339 Section \refersec{app:inliningexample1concreteinstance}.
1340
1341
1342 \subsubsection{Inlining example \#1: abstract instance}
1343 \label{app:inliningexample1abstractinstance}
1344 \begin{alltt}
1345     ! Abstract instance for OUTER
1346     !
1347 OUTER.AI.1.1:
1348     \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1349         DW\_AT\_name("OUTER")
1350         DW\_AT\_inline(DW\_INL\_declared\_inlined)
1351         ! No low/high PCs
1352 OUTER.AI.1.2:
1353         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1354             DW\_AT\_name("OUTER\_FORMAL")
1355             DW\_AT\_type(reference to integer)
1356             ! No location
1357 OUTER.AI.1.3:
1358         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1359             DW\_AT\_name("OUTER\_LOCAL")
1360             DW\_AT\_type(reference to integer)
1361             ! No location
1362         !
1363         ! Abstract instance for INNER
1364         !
1365 INNER.AI.1.1:
1366         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1367             DW\_AT\_name("INNER")
1368             DW\_AT\_inline(DW\_INL\_declared\_inlined)
1369             ! No low/high PCs
1370 INNER.AI.1.2:
1371             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1372                 DW\_AT\_name("INNER\_FORMAL")
1373                 DW\_AT\_type(reference to integer)
1374                 ! No location
1375 INNER.AI.1.3:
1376             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1377                 DW\_AT\_name("INNER\_LOCAL")
1378                 DW\_AT\_type(reference to integer)
1379                 ! No location
1380             ...
1381             0
1382         ! No \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine} (concrete instance)
1383         ! for INNER corresponding to calls of INNER
1384         ...
1385         0
1386 \end{alltt}
1387
1388
1389 \subsubsection{Inlining example \#1: concrete instance}
1390 \label{app:inliningexample1concreteinstance}
1391 \begin{alltt}
1392 ! Concrete instance for call "OUTER(7)"
1393 !
1394 OUTER.CI.1.1:
1395     \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
1396         ! No name
1397         DW\_AT\_abstract\_origin(reference to OUTER.AI.1.1)
1398         DW\_AT\_low\_pc(...)
1399         DW\_AT\_high\_pc(...)
1400 OUTER.CI.1.2:
1401         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1402             ! No name
1403             DW\_AT\_abstract\_origin(reference to OUTER.AI.1.2)
1404             DW\_AT\_const\_value(7)
1405 OUTER.CI.1.3:
1406         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1407             ! No name
1408             DW\_AT\_abstract\_origin(reference to OUTER.AI.1.3)
1409             DW\_AT\_location(...)
1410         !
1411         ! No \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram} (abstract instance) for INNER
1412         !
1413         ! Concrete instance for call INNER(OUTER\_LOCAL)
1414         !
1415 INNER.CI.1.1:
1416         \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
1417             ! No name
1418             DW\_AT\_abstract\_origin(reference to INNER.AI.1.1)
1419             DW\_AT\_low\_pc(...)
1420             DW\_AT\_high\_pc(...)
1421             DW\_AT\_static\_link(...)
1422 INNER.CI.1.2:
1423             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1424                 ! No name
1425                 DW\_AT\_abstract\_origin(reference to INNER.AI.1.2)
1426                 DW\_AT\_location(...)
1427 INNER.CI.1.3:
1428              \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1429                 ! No name
1430                 DW\_AT\_abstract\_origin(reference to INNER.AI.1.3)
1431                 DW\_AT\_location(...)
1432             ...
1433             0
1434         ! Another concrete instance of INNER within OUTER
1435         ! for the call "INNER(31)"
1436         ...
1437         0
1438 \end{alltt}
1439
1440 \subsection{Alternative 2: Inline OUTER, multiple INNERs}
1441 \label{app:inlineoutermultiipleinners}
1442
1443
1444 In the second alternative we assume that subprogram INNER
1445 is not inlinable for some reason, but subprogram OUTER is
1446 inlinable. Each concrete inlined instance of OUTER has its
1447 own normal instance of INNER. The abstract instance for OUTER,
1448 which includes INNER, is shown in 
1449 Section \refersec{app:inliningexample2abstractinstance}.
1450
1451 Note that the debugging information in this Figure differs from
1452 that in 
1453 Section \refersec{app:inliningexample1abstractinstance}
1454 in that INNER lacks a DW\_AT\_inline attribute
1455 and therefore is not a distinct abstract instance. INNER
1456 is merely an out\dash of\dash line routine that is part of OUTER’s
1457 abstract instance. This is reflected in the Figure 70 by
1458 the fact that the labels for INNER use the substring OUTER
1459 instead of INNER.
1460
1461 A resulting concrete inlined instance of OUTER is shown in
1462 Section \refersec{app:inliningexample2concreteinstance}.
1463
1464 Notice in 
1465 Section \refersec{app:inliningexample2concreteinstance}.
1466 that OUTER is expanded as a concrete
1467 inlined instance, and that INNER is nested within it as a
1468 concrete out\dash of\dash line subprogram. Because INNER is cloned
1469 for each inline expansion of OUTER, only the invariant
1470 attributes of INNER 
1471 (for example, DW\_AT\_name) are specified
1472 in the abstract instance of OUTER, and the low\dash level,
1473 instance\dash specific attributes of INNER (for example,
1474 DW\_AT\_low\_pc) are specified in each concrete instance of OUTER.
1475
1476 The several calls of INNER within OUTER are compiled as normal
1477 calls to the instance of INNER that is specific to the same
1478 instance of OUTER that contains the calls.
1479
1480
1481 \subsubsection{Inlining example 2: abstract instance}
1482 \label{app:inliningexample2abstractinstance}
1483 \begin{alltt}
1484     ! Abstract instance for OUTER
1485     !
1486 OUTER.AI.2.1:
1487     \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1488         DW\_AT\_name("OUTER")
1489         DW\_AT\_inline(DW\_INL\_declared\_inlined)
1490         ! No low/high PCs
1491 OUTER.AI.2.2:
1492         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1493             DW\_AT\_name("OUTER\_FORMAL")
1494             DW\_AT\_type(reference to integer)
1495             ! No location
1496 OUTER.AI.2.3:
1497         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1498             DW\_AT\_name("OUTER\_LOCAL")
1499             DW\_AT\_type(reference to integer)
1500             ! No location
1501         !
1502         ! Nested out-of-line INNER subprogram
1503         !
1504 OUTER.AI.2.4:
1505         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1506             DW\_AT\_name("INNER")
1507             ! No DW\_AT\_inline
1508             ! No low/high PCs, frame\_base, etc.
1509 OUTER.AI.2.5:
1510             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1511                 DW\_AT\_name("INNER\_FORMAL")
1512                 DW\_AT\_type(reference to integer)
1513                 ! No location
1514 OUTER.AI.2.6:
1515             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1516                 DW\_AT\_name("INNER\_LOCAL")
1517                 DW\_AT\_type(reference to integer)
1518                 ! No location
1519             ...
1520             0
1521         ...
1522         0
1523 \end{alltt}
1524
1525 \subsubsection{Inlining example 2: concrete instance}
1526 \label{app:inliningexample2concreteinstance}
1527 \begin{alltt}
1528
1529     ! Concrete instance for call "OUTER(7)"
1530     !
1531 OUTER.CI.2.1:
1532     \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
1533         ! No name
1534         DW\_AT\_abstract\_origin(reference to OUTER.AI.2.1)
1535         DW\_AT\_low\_pc(...)
1536         DW\_AT\_high\_pc(...)
1537 OUTER.CI.2.2:
1538         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1539             ! No name
1540             DW\_AT\_abstract\_origin(reference to OUTER.AI.2.2)
1541             DW\_AT\_location(...)
1542 OUTER.CI.2.3:
1543         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1544             ! No name
1545             DW\_AT\_abstract\_origin(reference to OUTER.AI.2.3)
1546             DW\_AT\_location(...)
1547         !
1548         ! Nested out-of-line INNER subprogram
1549         !
1550 OUTER.CI.2.4:
1551         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1552             ! No name
1553             DW\_AT\_abstract\_origin(reference to OUTER.AI.2.4)
1554             DW\_AT\_low\_pc(...)
1555             DW\_AT\_high\_pc(...)
1556             DW\_AT\_frame\_base(...)
1557             DW\_AT\_static\_link(...)
1558 OUTER.CI.2.5:
1559             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1560                 ! No name
1561                 DW\_AT\_abstract\_origin(reference to OUTER.AI.2.5)
1562                 DW\_AT\_location(...)
1563 OUTER.CI.2.6:
1564             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1565                 ! No name
1566                 DW\_AT\_abstract\_origin(reference to OUTER.AT.2.6)
1567                 DW\_AT\_location(...)
1568             ...
1569             0
1570         ...
1571         0
1572 \end{alltt}
1573
1574 \subsection{Alternative 3: inline OUTER, one normal INNER}
1575 \label{app:inlineouteronenormalinner}
1576
1577 In the third approach, one normal subprogram for INNER is
1578 compiled which is called from all concrete inlined instances of
1579 OUTER. The abstract instance for OUTER is shown in 
1580 Section \refersec{app:inliningexample3abstractinstance}.
1581
1582 The most distinctive aspect of that Figure is that subprogram
1583 INNER exists only within the abstract instance of OUTER,
1584 and not in OUTER’s concrete instance. In the abstract
1585 instance of OUTER, the description of INNER has the full
1586 complement of attributes that would be expected for a
1587 normal subprogram. While attributes such as DW\_AT\_low\_pc,
1588 DW\_AT\_high\_pc, DW\_AT\_location, and so on, typically are omitted
1589 from an abstract instance because they are not invariant across
1590 instances of the containing abstract instance, in this case
1591 those same attributes are included precisely because they are
1592 invariant -- there is only one subprogram INNER to be described
1593 and every description is the same.
1594
1595 A concrete inlined instance of OUTER is illustrated in
1596 \refersec{app:inliningexample3concreteinstance}.
1597
1598 Notice in 
1599 \refersec{app:inliningexample3abstractinstance}
1600 that there is no DWARF representation for
1601 INNER at all; the representation of INNER does not vary across
1602 instances of OUTER and the abstract instance of OUTER includes
1603 the complete description of INNER, so that the description of
1604 INNER may be (and for reasons of space efficiency, should be)
1605 omitted from each concrete instance of OUTER.
1606
1607 There is one aspect of this approach that is problematical from
1608 the DWARF perspective. The single compiled instance of INNER
1609 is assumed to access up\dash level variables of OUTER; however,
1610 those variables may well occur at varying positions within
1611 the frames that contain the concrete inlined instances. A
1612 compiler might implement this in several ways, including the
1613 use of additional compiler generated parameters that provide
1614 reference parameters for the up\dash level variables, or a compiler
1615 generated static link like parameter that points to the group
1616 of up\dash level entities, among other possibilities. In either of
1617 these cases, the DWARF description for the location attribute
1618 of each uplevel variable needs to be different if accessed
1619 from within INNER compared to when accessed from within the
1620 instances of OUTER. An implementation is likely to require
1621 vendor\dash specific DWARF attributes and/or debugging information
1622 entries to describe such cases.
1623
1624 Note that in C++, a member function of a class defined within
1625 a function definition does not require any vendor\dash specific
1626 extensions because the C++ language disallows access to
1627 entities that would give rise to this problem. (Neither extern
1628 variables nor static members require any form of static link
1629 for accessing purposes.)
1630
1631 \subsubsection{Inlining example 3: abstract instance}
1632 \label{app:inliningexample3abstractinstance}
1633 \begin{alltt}
1634     ! Abstract instance for OUTER
1635     !
1636 OUTER.AI.3.1:
1637     \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1638         DW\_AT\_name("OUTER")
1639         DW\_AT\_inline(DW\_INL\_declared\_inlined)
1640         ! No low/high PCs
1641 OUTER.AI.3.2:
1642         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1643             DW\_AT\_name("OUTER\_FORMAL")
1644             DW\_AT\_type(reference to integer)
1645             ! No location
1646 OUTER.AI.3.3:
1647         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1648             DW\_AT\_name("OUTER\_LOCAL")
1649             DW\_AT\_type(reference to integer)
1650             ! No location
1651         !
1652         ! Normal INNER
1653         !
1654 OUTER.AI.3.4:
1655         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1656             DW\_AT\_name("INNER")
1657             DW\_AT\_low\_pc(...)
1658             DW\_AT\_high\_pc(...)
1659             DW\_AT\_frame\_base(...)
1660             DW\_AT\_static\_link(...)
1661 OUTER.AI.3.5:
1662             \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1663                 DW\_AT\_name("INNER\_FORMAL")
1664                 DW\_AT\_type(reference to integer)
1665                 DW\_AT\_location(...)
1666 OUTER.AI.3.6:
1667             \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1668                 DW\_AT\_name("INNER\_LOCAL")
1669                 DW\_AT\_type(reference to integer)
1670                 DW\_AT\_location(...)
1671             ...
1672             0
1673         ...
1674         0
1675 \end{alltt}
1676
1677
1678 \subsubsection{Inlining example 3: concrete instance}
1679 \label{app:inliningexample3concreteinstance}
1680 \begin{alltt}
1681     ! Concrete instance for call "OUTER(7)"
1682     !
1683 OUTER.CI.3.1:
1684     \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
1685         ! No name
1686         DW\_AT\_abstract\_origin(reference to OUTER.AI.3.1)
1687         DW\_AT\_low\_pc(...)
1688         DW\_AT\_high\_pc(...)
1689         DW\_AT\_frame\_base(...)
1690 OUTER.CI.3.2:
1691         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1692             ! No name
1693             DW\_AT\_abstract\_origin(reference to OUTER.AI.3.2)
1694             ! No type
1695             DW\_AT\_location(...)
1696 OUTER.CI.3.3:
1697         \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1698             ! No name
1699             DW\_AT\_abstract\_origin(reference to OUTER.AI.3.3)
1700             ! No type
1701             DW\_AT\_location(...)
1702         ! No \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram} for "INNER"
1703         ...
1704         0
1705 \end{alltt}
1706
1707 \section{Constant Expression Example}
1708 \label{app:constantexpressionexample}
1709 C++ generalizes the notion of constant expressions to include
1710 constant expression user-defined literals and functions.
1711
1712 \begin{figure}[here]
1713 \begin{lstlisting}
1714 constexpr double mass = 9.8;
1715 constexpr int square (int x) { return x * x; }
1716 float arr[square(9)]; // square() called and inlined
1717 \end{lstlisting}
1718 \caption{Constant expressions: C++ source} \label{fig:constantexpressionscsource}
1719 \end{figure}
1720
1721 These declarations can be represented as illustrated in 
1722 Section \refersec{app:constantexpressionsdwarfdescription}.
1723
1724 \subsection{Constant expressions: DWARF description}
1725 \label{app:constantexpressionsdwarfdescription}
1726 \begin{alltt}
1727
1728       ! For variable mass
1729       !
1730 1\$:  \livelink{chap:DWTAGconsttype}{DW\_TAG\_const\_type}
1731         DW\_AT\_type(reference to "double")
1732 2\$:  \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1733         DW\_AT\_name("mass")
1734         DW\_AT\_type(reference to 1\$)
1735         DW\_AT\_const\_expr(true)
1736         DW\_AT\_const\_value(9.8)
1737       ! Abstract instance for square
1738       !
1739 10\$: \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1740         DW\_AT\_name("square")
1741         DW\_AT\_type(reference to "int")
1742         DW\_AT\_inline(DW\_INL\_inlined)
1743 11\$:   \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1744             DW\_AT\_name("x")
1745             DW\_AT\_type(reference to "int")
1746       ! Concrete instance for square(9)
1747       !
1748 20\$: \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
1749         DW\_AT\_abstract\_origin(reference to 10\$)
1750         DW\_AT\_const\_expr(present)
1751         DW\_AT\_const\_value(81)
1752         \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1753             DW\_AT\_abstract\_origin(reference to 11\$)
1754             DW\_AT\_const\_value(9)
1755       ! Anonymous array type for arr
1756       !
1757 30\$: \livelink{chap:DWTAGarraytype}{DW\_TAG\_array\_type}
1758         DW\_AT\_type(reference to "float")
1759         DW\_AT\_byte\_size(324) ! 81*4
1760         \livelink{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}
1761             DW\_AT\_type(reference to "int")
1762             DW\_AT\_upper\_bound(reference to 20\$)
1763       ! Variable arr
1764       !
1765 40\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1766         DW\_AT\_name("arr")
1767         DW\_AT\_type(reference to 30\$)
1768 \end{alltt}
1769
1770
1771 \section{Unicode Character Example}
1772 \label{app:unicodecharacterexample}
1773
1774 Unicode character encodings can be described in DWARF as
1775 illustrated in 
1776 Section \refersec{app:unicodecharacterexamplesub}.
1777
1778 \begin{lstlisting}
1779 // C++ source
1780 //
1781 char16_t chr_a = u'h';
1782 char32_t chr_b = U'h';
1783 \end{lstlisting}
1784
1785 \subsection{Unicode Character Example}
1786 \label{app:unicodecharacterexamplesub}
1787 \begin{alltt}
1788
1789 ! DWARF description
1790 !
1791 1\$: \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
1792         DW\_AT\_name("char16\_t")
1793         DW\_AT\_encoding(DW\_ATE\_UTF)
1794         DW\_AT\_byte\_size(2)
1795 2\$: \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
1796         DW\_AT\_name("char32\_t")
1797         DW\_AT\_encoding(DW\_ATE\_UTF)
1798         DW\_AT\_byte\_size(4)
1799 3\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1800         DW\_AT\_name("chr\_a")
1801         DW\_AT\_type(reference to 1\$)
1802 4\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1803         DW\_AT\_name("chr\_b")
1804         DW\_AT\_type(reference to 2\$)
1805 \end{alltt}
1806
1807
1808
1809 \section{Type-Safe Enumeration Example}
1810 \label{app:typesafeenumerationexample}
1811
1812
1813 C++ type\dash safe enumerations can be described in DWARF as illustrated in 
1814 Section \refersec{app:ctypesafeenumerationexample}.
1815
1816 \begin{lstlisting}
1817 // C++ source
1818 //
1819 enum class E { E1, E2=100 };
1820 E e1;
1821 \end{lstlisting}
1822
1823 \subsection{C++ type-safe enumeration example}
1824 \label{app:ctypesafeenumerationexample}
1825 \begin{alltt}
1826 ! DWARF description
1827 !
1828 11\$: \livelink{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}
1829         DW\_AT\_name("E")
1830         DW\_AT\_type(reference to "int")
1831         DW\_AT\_enum\_class(present)
1832 12\$:   \livelink{chap:DWTAGenumerator}{DW\_TAG\_enumerator}
1833             DW\_AT\_name("E1")
1834             DW\_AT\_const\_value(0)
1835 13\$:
1836          \livelink{chap:DWTAGenumerator}{DW\_TAG\_enumerator}
1837             DW\_AT\_name("E2")
1838             DW\_AT\_const\_value(100)
1839 14\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1840         DW\_AT\_name("e1")
1841         DW\_AT\_type(reference to 11\$)
1842 \end{alltt}
1843
1844 \section{Template Example}
1845 \label{app:templateexample}
1846
1847 C++ templates can be described in DWARF as illustrated in 
1848 Section \refersec{app:ctemplateexample1}.
1849
1850
1851
1852 \begin{lstlisting}
1853 // C++ source
1854 //
1855 template<class T>
1856 struct wrapper {
1857     T comp;
1858 };
1859 wrapper<int> obj;
1860 \end{lstlisting}
1861
1862 \subsection{C++ template example 1}
1863 \label{app:ctemplateexample1}
1864 \begin{alltt}
1865 ! DWARF description
1866 !
1867 11\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
1868         DW\_AT\_name("wrapper")
1869 12\$: \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
1870         DW\_AT\_name("T")
1871         DW\_AT\_type(reference to "int")
1872 13\$ \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1873         DW\_AT\_name("comp")
1874         DW\_AT\_type(reference to 12\$)
1875 14\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1876         DW\_AT\_name("obj")
1877         DW\_AT\_type(reference to 11\$)
1878 \end{alltt}
1879
1880 The actual type of the component comp is int, but in the DWARF
1881 the type references the \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter} for
1882 T, which in turn references int. This implies that in the
1883 original template comp was of type T and that was replaced
1884 with int in the instance.  There exist situations where it is
1885 not possible for the DWARF to imply anything about the nature
1886 of the original template. 
1887
1888 Consider following C++ source and DWARF 
1889 that can describe it in
1890 Section \refersec{app:ctemplateexample2}.
1891
1892
1893 \begin{lstlisting}
1894 // C++ source
1895 //
1896     template<class T>
1897     struct wrapper {
1898         T comp;
1899     };
1900     template<class U>
1901     void consume(wrapper<U> formal)
1902     {
1903         ...
1904     }
1905     wrapper<int> obj;
1906     consume(obj);
1907 \end{lstlisting}
1908
1909 \subsection{C++ template example 2}
1910 \label{app:ctemplateexample2}
1911 \begin{alltt}
1912 ! DWARF description
1913 !
1914 11\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
1915         DW\_AT\_name("wrapper")
1916 12\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
1917             DW\_AT\_name("T")
1918             DW\_AT\_type(reference to "int")
1919 13\$    \livelink{chap:DWTAGmember}{DW\_TAG\_member}
1920             DW\_AT\_name("comp")
1921             DW\_AT\_type(reference to 12\$)
1922 14\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
1923         DW\_AT\_name("obj")
1924         DW\_AT\_type(reference to 11\$)
1925 21\$: \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
1926         DW\_AT\_name("consume")
1927 22\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
1928             DW\_AT\_name("U")
1929             DW\_AT\_type(reference to "int")
1930 23\$:   \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter}
1931             DW\_AT\_name("formal")
1932             DW\_AT\_type(reference to 11\$)
1933 \end{alltt}
1934
1935 In the \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram} entry for the instance of consume,
1936 U is described as 
1937 int. 
1938 The type of formal is 
1939 \begin{alltt}
1940 wrapper<U>
1941 \end{alltt}
1942  in
1943 the source. DWARF only represents instantiations of templates;
1944 there is no entry which represents 
1945 \begin{alltt}
1946 wrapper<U>, 
1947 \end{alltt}
1948 which is neither
1949 a template parameter nor a template instantiation. The type
1950 of formal is described as 
1951 \begin{alltt}
1952 wrapper<int>, 
1953 \end{alltt}
1954 the instantiation of
1955 \begin{alltt}
1956 wrapper<U>, 
1957 \end{alltt}
1958 in the DW\_AT\_type attribute at 
1959 23\$. 
1960 There is no
1961 description of the relationship between template type parameter
1962 T at 12\$ and U at 
1963 22\$ which was used to instantiate 
1964 \begin{alltt}
1965 wrapper<U>.
1966 \end{alltt}
1967
1968 A consequence of this is that the DWARF information would
1969 not distinguish between the existing example and one where
1970 the formal of consume were declared in the source to be
1971 \begin{alltt}
1972 wrapper<int>.
1973 \end{alltt}
1974
1975 \section{Template Alias Examples}
1976 \label{app:templatealiasexample}
1977
1978 C++ template aliases can be described in DWARF as illustrated in 
1979 Section \refersec{app:templatealiasexample1}
1980 and 
1981 Section \refersec{app:templatealiasexample2}.
1982
1983
1984 \begin{lstlisting}
1985 // C++ source, template alias example 1
1986 //
1987 template<typename T, typename U>
1988 struct Alpha {
1989     T tango;
1990     U uniform;
1991 };
1992 template<typename V> using Beta = Alpha<V,V>;
1993 Beta<long> b;
1994 \end{lstlisting}
1995
1996
1997 \subsection{template alias example 1}
1998 \label{app:templatealiasexample1}
1999 \begin{alltt}
2000 ! DWARF representation for variable 'b'
2001 !
2002 20\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2003         DW\_AT\_name("Alpha")
2004 21\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2005             DW\_AT\_name("T")
2006             DW\_AT\_type(reference to "long")
2007 22\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2008             DW\_AT\_name("U")
2009             DW\_AT\_type(reference to "long")
2010 23\$:   \livelink{chap:DWTAGmember}{DW\_TAG\_member}
2011             DW\_AT\_name("tango")
2012             DW\_AT\_type(reference to 21\$)
2013 24\$:   \livelink{chap:DWTAGmember}{DW\_TAG\_member}
2014             DW\_AT\_name("uniform")
2015             DW\_AT\_type(reference to 22\$)
2016 25\$: \livelink{chap:DWTAGtemplatealias}{DW\_TAG\_template\_alias}
2017         DW\_AT\_name("Beta")
2018         DW\_AT\_type(reference to 20\$)
2019 26\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2020             DW\_AT\_name("V")
2021             DW\_AT\_type(reference to "long")
2022 27\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2023         DW\_AT\_name("b")
2024         DW\_AT\_type(reference to 25\$)
2025 \end{alltt}
2026
2027
2028 \begin{lstlisting}
2029 // C++ source, template alias example 2
2030 //
2031 template<class TX> struct X { };
2032 template<class TY> struct Y { };
2033 template<class T> using Z = Y<T>;
2034 X<Y<int>> y;
2035 X<Z<int>> z;
2036 \end{lstlisting}
2037
2038
2039 \subsection{template alias example 2}
2040 \label{app:templatealiasexample2}
2041 \begin{alltt}
2042 ! DWARF representation for X<Y<int>>
2043 !
2044 30\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2045         DW\_AT\_name("Y")
2046 31\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2047             DW\_AT\_name("TY")
2048             DW\_AT\_type(reference to "int")
2049 32\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2050         DW\_AT\_name("X")
2051 33\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2052             DW\_AT\_name("TX")
2053             DW\_AT\_type(reference to 30\$)
2054
2055 ! DWARF representation for X<Z<int>>
2056 !
2057 40\$: \livelink{chap:DWTAGtemplatealias}{DW\_TAG\_template\_alias}
2058 using Z = Y<int>;
2059         DW\_AT\_name("Z")
2060         DW\_AT\_type(reference to 30\$)
2061 41\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2062             DW\_AT\_name("T")
2063             DW\_AT\_type(reference to "int")
2064 42\$: \livelink{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type}
2065         DW\_AT\_name("X")
2066 43\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}
2067             DW\_AT\_name("TX")
2068             DW\_AT\_type(reference to 40\$)
2069 ! Note that 32\$ and 42\$ are actually the same type
2070 !
2071 50\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2072         DW\_AT\_name("y")
2073         DW\_AT\_type(reference to \$32)
2074 51\$: \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}
2075         DW\_AT\_name("z")
2076         DW\_AT\_type(reference to \$42)
2077 \end{alltt}