61166ab127b073d43144c6b24536a4de5caf9f0f
[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 \section{Compilation Units and Abbreviations Table Example}
9 \label{app:compilationunitsandabbreviationstableexample}
10
11
12 Figure \refersec{fig:compilationunitsandabbreviationstable}
13 depicts the relationship of the abbreviations tables contained
14 \addtoindexx{abbreviations table!example}
15 \addtoindexx{\texttt{.debug\_abbrev}!example}
16 \addtoindexx{\texttt{.debug\_info}!example}
17 in the \dotdebugabbrev{}
18 section to the information contained in
19 the \dotdebuginfo{}
20 section. Values are given in symbolic form,
21 where possible.
22
23 The figure corresponds to the following two trivial source files:
24
25 File myfile.c
26 \begin{lstlisting}[numbers=none]
27 typedef char* POINTER;
28 \end{lstlisting}
29 File myfile2.c
30 \begin{lstlisting}[numbers=none]
31 typedef char* strp;
32 \end{lstlisting}
33
34 % Ensures we get the following float out before we go on.
35 \clearpage
36 \begin{figure}[here]
37 %\centering
38 %\setlength{\linewidth}{1.1\linewidth}
39 \begin{minipage}[t]{0.03\linewidth}
40 \flushright
41 \scriptsize
42 % Note: alltt is used to step down the needed number of lines to the labels
43 \begin{alltt}
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64 \textit{e1:}
65
66
67
68
69 \textit{e2:}
70 \end{alltt}
71 \end{minipage}
72 %
73 \begin{minipage}[t]{0.38\linewidth}
74 \centering
75 Compilation Unit \#1: \dotdebuginfo{}
76 \begin{framed}
77 \scriptsize
78 \begin{alltt}
79 \textit{length}
80 4
81 \textit{a1 (abbreviations table offset)}
82 4
83 \vspace{0.01cm}
84 \hrule
85 1
86 "myfile.c"
87 "Best Compiler Corp, V1.3"
88 "/home/mydir/src"
89 \DWLANGCeightynine
90 0x0
91 0x55
92 \DWFORMsecoffset
93 0x0
94 \vspace{0.01cm}
95 \hrule
96 2
97 "char"
98 \DWATEunsignedchar
99 1
100 \vspace{0.01cm}
101 \hrule
102 3
103 \textit{e1  (debug info offset)}
104 \vspace{0.01cm}
105 \hrule
106 4
107 "POINTER"
108 \textit{e2  (debug info offset)}
109 \vspace{0.01cm}
110 \hrule
111 0
112 \end{alltt}
113 %
114 %
115 \end{framed}
116 Compilation Unit \#2: \dotdebuginfo{}
117 \begin{framed}
118 \scriptsize
119 \begin{alltt}
120 \textit{length}
121 4
122 \textit{a1 (abbreviations table offset)}
123 4
124 \vspace{0.01cm}
125 \hrule
126 ...
127 \vspace{0.01cm}
128 \hrule
129 4
130 "strp"
131 \textit{e2  (debug info offset)}
132 \vspace{0.01cm}
133 \hrule
134 ...
135 \end{alltt}
136 %
137 %
138 \end{framed}
139 \end{minipage}
140 \hfill 
141 % Place the label for the abbreviation table
142 \begin{minipage}[t]{0.03\linewidth}
143 \flushright
144 \scriptsize
145 % Note: alltt is used to step down the needed number of lines to the label
146 \begin{alltt}
147
148
149
150
151
152 \textit{a1:}
153 \end{alltt}
154 \end{minipage}
155 %
156 \begin{minipage}[t]{0.41\linewidth}
157 \centering
158 Abbreviation Table: \dotdebugabbrev{}
159 \begin{framed}
160 \scriptsize
161 \begin{alltt}\vspace{0.06cm}
162 1
163 \DWTAGcompileunit
164 \DWCHILDRENyes
165 \DWATname       \DWFORMstring
166 \DWATproducer   \DWFORMstring
167 \DWATcompdir   \DWFORMstring
168 \DWATlanguage   \DWFORMdataone
169 \DWATlowpc     \DWFORMaddr
170 \DWAThighpc    \DWFORMdataone
171 \DWATstmtlist  \DWFORMindirect
172 0
173 \vspace{0.01cm}
174 \hrule
175 2
176 \DWTAGbasetype
177 \DWCHILDRENno
178 \DWATname       \DWFORMstring
179 \DWATencoding   \DWFORMdataone
180 \DWATbytesize  \DWFORMdataone
181 0
182 \vspace{0.01cm}
183 \hrule
184 3
185 \DWTAGpointertype
186 \DWCHILDRENno
187 \DWATtype       \DWFORMreffour
188 0
189 \vspace{0.01cm}
190 \hrule
191 4
192 \DWTAGtypedef
193 \DWCHILDRENno
194 \DWATname      \DWFORMstring
195 \DWATtype      \DWFORMrefaddr
196 0
197 \vspace{0.01cm}
198 \hrule
199 0
200 \end{alltt}
201 \end{framed}
202 \end{minipage}
203
204 \vspace{0.2cm}
205 \caption{Compilation units and abbreviations table} \label{fig:compilationunitsandabbreviationstable}
206 \end{figure}
207
208 % Ensures we get the above float out before we go on.
209 \clearpage
210
211 \section{Aggregate Examples}
212 \label{app:aggregateexamples}
213
214 The following examples illustrate how to represent some of
215 the more complicated forms of array and record aggregates
216 using DWARF.
217
218 \subsection{Fortran Simple Array Example}
219 \label{app:fortranarrayexample}
220 Consider the \addtoindex{Fortran array}\addtoindexx{Fortran 90} source fragment in 
221 \addtoindexx{array type entry!examples}
222 Figure \referfol{fig:fortranarrayexamplesourcefragment}.
223
224 \begin{figure}[here]
225 \begin{lstlisting}
226 type array_ptr
227 real :: myvar
228 real, dimension (:), pointer :: ap
229 end type array_ptr
230 type(array_ptr), allocatable, dimension(:) :: arrayvar
231 allocate(arrayvar(20))
232 do i = 1, 20
233 allocate(arrayvar(i)%ap(i+10))
234 end do
235 \end{lstlisting}
236 \caption{Fortran array example: source fragment} \label{fig:fortranarrayexamplesourcefragment}
237 \end{figure}
238
239 For allocatable and pointer arrays, it is essentially required
240 by the \addtoindex{Fortran array} semantics that each array consist of 
241 \addtoindexx{descriptor!array}
242 two
243 \addtoindexx{array!descriptor for}
244 parts, which we here call 1) the descriptor and 2) the raw
245 data. (A descriptor has often been called a dope vector in
246 other contexts, although it is often a structure of some kind
247 rather than a simple vector.) Because there are two parts,
248 and because the lifetime of the descriptor is necessarily
249 longer than and includes that of the raw data, there must be
250 an address somewhere in the descriptor that points to the
251 raw data when, in fact, there is some (that is, when 
252 the \doublequote{variable} is allocated or associated).
253
254 For concreteness, suppose that a descriptor looks something
255 like the C structure in 
256 Figure \refersec{fig:fortranarrayexampledescriptorrepresentation}.
257 Note, however, that it is
258 a property of the design that 1) a debugger needs no builtin
259 knowledge of this structure and 2) there does not need to
260 be an explicit representation of this structure in the DWARF
261 input to the debugger.
262
263 \begin{figure}[here]
264 \begin{lstlisting}
265 struct desc {
266     long el_len;       // Element length
267     void * base;       // Address of raw data
268     int ptr_assoc : 1; // Pointer is associated flag
269     int ptr_alloc : 1; // Pointer is allocated flag
270     int num_dims  : 6; // Number of dimensions
271     struct dims_str {  // For each dimension...  
272         long low_bound;
273         long upper_bound;
274         long stride;
275     } dims[63];
276 };
277 \end{lstlisting}
278 \caption{Fortran array example: descriptor representation}
279 \label{fig:fortranarrayexampledescriptorrepresentation}
280 \end{figure}
281
282
283 In practice, of course, a \doublequote{real} descriptor will have
284 dimension substructures only for as many dimensions as are
285 specified in the \texttt{num\_dims} component. Let us use the notation
286 \texttt{desc\textless n\textgreater}   
287 to indicate a specialization of the \texttt{desc} struct in
288 which \texttt{n} is the bound for the \texttt{dims} component as well as the
289 contents of the \texttt{num\_dims} component.
290
291 Because the arrays considered here come in two parts, it is
292 necessary to distinguish the parts carefully. In particular,
293 the \doublequote{address of the variable} or equivalently, the \doublequote{base
294 address of the object} \emph{always} refers to the descriptor. For
295 arrays that do not come in two parts, an implementation can
296 provide a descriptor anyway, thereby giving it two parts. (This
297 may be convenient for general runtime support unrelated to
298 debugging.) In this case the above vocabulary applies as
299 stated. Alternatively, an implementation can do without a
300 descriptor, in which case the \doublequote{address of the variable,}
301 or equivalently the \doublequote{base address of the object}, refers
302 to the \doublequote{raw data} (the real data, the only thing around
303 that can be the object).
304
305 If an object has a descriptor, then the DWARF type for that
306 object will have a 
307 \DWATdatalocation{} 
308 attribute. If an object
309 does not have a descriptor, then usually the DWARF type for the
310 object will not have a 
311 \DWATdatalocation. 
312 (See the following
313 \addtoindex{Ada} example for a case where the type for an object without
314 a descriptor does have a 
315 \DWATdatalocation{} attribute. In
316 that case the object doubles as its own descriptor.)
317
318 The \addtoindex{Fortran} derived type \texttt{array\_ptr} can now be redescribed
319 in C\dash like terms that expose some of the representation as in
320
321 \begin{lstlisting}[numbers=none]
322 struct array_ptr {
323     float myvar;
324     desc<1> ap;
325 };
326 \end{lstlisting}
327
328 Similarly for variable \texttt{arrayvar}:
329 \begin{lstlisting}[numbers=none]
330 desc<1> arrayvar;
331 \end{lstlisting}
332
333 (Recall that \texttt{desc\textless 1\textgreater} 
334 indicates the 1\dash dimensional version of \texttt{desc}.)
335
336 \newpage
337 Finally, the following notation is useful:
338 \begin{enumerate}[1. ]
339 \item  sizeof(type): size in bytes of entities of the given type
340 \item offset(type, comp): offset in bytes of the comp component
341 within an entity of the given type
342 \end{enumerate}
343
344 The DWARF description is shown 
345 \addtoindexx{Fortran 90}
346 in Figure \refersec{fig:fortranarrayexampledwarfdescription}.
347
348 \begin{figure}[h]
349 \figurepart{1}{2}
350 \begin{dwflisting}
351 \begin{alltt}
352 ! Description for type of 'ap'
353 !
354 1\$: \DWTAGarraytype
355         ! No name, default (Fortran) ordering, default stride
356         \DWATtype(reference to REAL)
357         \DWATassociated(expression=    ! Test 'ptr\_assoc' \nolink{flag}
358             \DWOPpushobjectaddress
359             \DWOPlitn                ! where n == offset(ptr\_assoc)
360             \DWOPplus
361             \DWOPderef
362             \DWOPlitone                  ! mask for 'ptr\_assoc' \nolink{flag}
363             \DWOPand)
364         \DWATdatalocation(expression= ! Get raw data address
365             \DWOPpushobjectaddress
366             \DWOPlitn                ! where n == offset(base)
367             \DWOPplus
368             \DWOPderef)                ! Type of index of array 'ap'
369 2\$:     \DWTAGsubrangetype
370             ! No name, default stride
371             \DWATtype(reference to INTEGER)
372             \DWATlowerbound(expression=
373                 \DWOPpushobjectaddress
374                 \DWOPlitn             ! where n ==
375                                          !   offset(desc, dims) +
376                                          !   offset(dims\_str, lower\_bound)
377                 \DWOPplus
378                 \DWOPderef)
379             \DWATupperbound(expression=
380                 \DWOPpushobjectaddress
381                 \DWOPlitn            ! where n ==
382                                         !   offset(desc, dims) +
383                                         !   offset(dims\_str, upper\_bound)
384                 \DWOPplus
385                 \DWOPderef)
386             !  Note: for the m'th dimension, the second operator becomes
387             !  \DWOPlitn where
388             !       n == offset(desc, dims)          +
389             !                (m-1)*sizeof(dims\_str)  +
390             !                 offset(dims\_str, [lower|upper]\_bound)
391             !  That is, the expression does not get longer for each successive 
392             !  dimension (other than to express the larger offsets involved).
393 \end{alltt}
394 \end{dwflisting}
395 \caption{Fortran array example: DWARF description}
396 \label{fig:fortranarrayexampledwarfdescription}
397 \end{figure}
398
399 \begin{figure}
400 \figurepart{2}{2}
401 \begin{dwflisting}
402 \begin{alltt}
403 3\$: \DWTAGstructuretype
404         \DWATname("array\_ptr")
405         \DWATbytesize(constant sizeof(REAL) + sizeof(desc<1>))
406 4\$:     \DWTAGmember
407             \DWATname("myvar")
408             \DWATtype(reference to REAL)
409             \DWATdatamemberlocation(constant 0)
410 5\$:     \DWTAGmember
411             \DWATname("ap");
412             \DWATtype(reference to 1\$)
413             \DWATdatamemberlocation(constant sizeof(REAL))
414 6\$: \DWTAGarraytype
415         ! No name, default (Fortran) ordering, default stride
416         \DWATtype(reference to 3\$)
417         \DWATallocated(expression=       ! Test 'ptr\_alloc' \nolink{flag}
418             \DWOPpushobjectaddress
419             \DWOPlitn                  ! where n == offset(ptr\_alloc)
420             \DWOPplus
421             \DWOPderef
422             \DWOPlittwo                    ! Mask for 'ptr\_alloc' \nolink{flag}
423             \DWOPand)
424         \DWATdatalocation(expression=   ! Get raw data address
425             \DWOPpushobjectaddress
426             \DWOPlitn                  ! where n == offset(base)
427             \DWOPplus
428             \DWOPderef)
429 7\$:     \DWTAGsubrangetype
430             ! No name, default stride
431             \DWATtype(reference to INTEGER)
432             \DWATlowerbound(expression=
433                 \DWOPpushobjectaddress
434                 \DWOPlitn              ! where n == ...
435                 \DWOPplus
436                 \DWOPderef)
437             \DWATupperbound(expression=
438                 \DWOPpushobjectaddress
439                 \DWOPlitn              ! where n == ...
440                 \DWOPplus
441                 \DWOPderef)
442 8\$: \DWTAGvariable
443         \DWATname("arrayvar")
444         \DWATtype(reference to 6\$)
445         \DWATlocation(expression=
446             ...as appropriate...)       ! Assume static allocation
447 \end{alltt}
448 \end{dwflisting}
449 \begin{center}
450
451 Figure~\ref{fig:fortranarrayexampledwarfdescription} Fortran array example: DWARF description \textit{(concluded)}
452 \end{center}
453 \end{figure}
454
455 Suppose 
456 \addtoindexx{Fortran array example}
457 the program is stopped immediately following completion
458 of the do loop. Suppose further that the user enters the
459 following debug command:
460
461 \begin{lstlisting}[numbers=none]
462 debug> print arrayvar(5)%ap(2)
463 \end{lstlisting}
464
465 Interpretation of this expression proceeds as follows:
466 \begin{enumerate}[1. ]
467
468 \item Lookup name \texttt{arrayvar}. We find that it is a variable,
469 whose type is given by the unnamed type at 6\$. Notice that
470 the type is an array type.
471
472
473 \item Find the 5$^{th}$ element of that array object. To do array
474 indexing requires several pieces of information:
475 \begin{enumerate}[a) ]
476
477 \item  the address of the array data
478
479 \item the lower bounds of the array \\
480 % Using plain [] here gives trouble.
481 \lbrack To check that 5 is within bounds would require the upper
482 bound too, but we will skip that for this example. \rbrack
483
484 \item the stride 
485
486 \end{enumerate}
487
488 For a), check for a 
489 \DWATdatalocation{} attribute. 
490 Since there is one, go execute the expression, whose result is
491 the address needed. The object address used in this case
492 is the object we are working on, namely the variable named
493 \texttt{arrayvar}, whose address was found in step 1. (Had there been
494 no \DWATdatalocation{} attribute, the desired address would
495 be the same as the address from step 1.)
496
497 For b), for each dimension of the array (only one
498 in this case), go interpret the usual lower bound
499 attribute. Again this is an expression, which again begins
500 with \DWOPpushobjectaddress. This object is 
501 \textbf{still} \texttt{arrayvar},
502 from step 1, because we have not begun to actually perform
503 any indexing yet.
504
505 For c), the default stride applies. Since there is no
506 \DWATbytestride{} attribute, use the size of the array element
507 type, which is the size of type \texttt{array\_ptr} (at 3\$).
508
509 \clearpage
510
511 Having acquired all the necessary data, perform the indexing
512 operation in the usual manner--which has nothing to do with
513 any of the attributes involved up to now. Those just provide
514 the actual values used in the indexing step.
515
516 The result is an object within the memory that was dynamically
517 allocated for \texttt{arrayvar}.
518
519 \item  Find the \texttt{ap} component of the object just identified,
520 whose type is \texttt{array\_ptr}.
521
522 This is a conventional record component lookup and
523 interpretation. It happens that the \texttt{ap} component in this case
524 begins at offset 4 from the beginning of the containing object.
525 Component \texttt{ap} has the unnamed array type defined at 1\$ in the
526 symbol table.
527
528 \item  Find the second element of the array object found in step 3. To do array indexing requires
529 several pieces of information:
530 \begin{enumerate}[a) ]
531 \item  the address of the array storage
532
533 \item  the lower bounds of the array \\
534 % Using plain [] here gives trouble.
535 \lbrack To check that 2 is within bounds we would require the upper
536 bound too, but we will skip that for this example \rbrack
537
538 \item  the stride
539
540 \end{enumerate}
541 \end{enumerate}
542
543 This is just like step 2), so the details are omitted. Recall
544 that because the DWARF type 1\$ has a \DWATdatalocation,
545 the address that results from step 4) is that of a
546 descriptor, and that address is the address pushed by the
547 \DWOPpushobjectaddress{} operations in 1\$ and 2\$.
548
549 Note: we happen to be accessing a pointer array here instead
550 of an allocatable array; but because there is a common
551 underlying representation, the mechanics are the same. There
552 could be completely different descriptor arrangements and the
553 mechanics would still be the same---only the stack machines
554 would be different.
555
556 %\needlines{8}
557 \subsection{Fortran Coarray Examples}
558 \label{app:Fortrancoarrayexamples}
559
560 \subsubsection{Fortran Scalar Coarray Example}
561 The \addtoindex{Fortran} scalar coarray example
562 \addtoindexx{coarray!example}\addtoindexx{scalar coarray|see{coarray}}
563 in Figure \refersec{fig:Fortranscalarcoarraysourcefragment} can be described as 
564 illustrated in Figure \refersec{fig:FortranscalarcoarrayDWARFdescription}.
565
566 \begin{figure}[!h]
567 \begin{lstlisting}
568         INTEGER X[*]
569 \end{lstlisting}
570 \caption{Fortran scalar coarray: source fragment}
571 \label{fig:Fortranscalarcoarraysourcefragment}
572 \end{figure}
573
574 \begin{figure}[!h]
575 \begin{dwflisting}
576 \begin{alltt}
577 10\$:  \DWTAGcoarraytype
578         \DWATtype(reference to INTEGER)
579         \DWTAGsubrangetype                ! Note omitted upper bound                    
580             \DWATlowerbound(constant 1)
581
582 11\$:  \DWTAGvariable
583         \DWATname("X")
584         \DWATtype(reference to coarray type at 10\$)
585 \end{alltt}
586 \end{dwflisting}
587 \caption{Fortran scalar coarray: DWARF description}
588 \label{fig:FortranscalarcoarrayDWARFdescription}
589 \end{figure}
590
591 \subsubsection{Fortran Array Coarray Example}
592 The \addtoindex{Fortran} (simple) array coarray example
593 \addtoindexx{coarray!example}\addtoindexx{array coarray|see{coarray}}
594 in Figure \refersec{fig:Fortranarraycoarraysourcefragment} can be described as 
595 illustrated in Figure \refersec{fig:FortranarraycoarrayDWARFdescription}.
596
597 \begin{figure}[here]
598 \begin{lstlisting}
599         INTEGER X(10)[*]
600 \end{lstlisting}
601 \caption{Fortran array coarray: source fragment}
602 \label{fig:Fortranarraycoarraysourcefragment}
603 \end{figure}
604
605 \begin{figure}[here]
606 \begin{dwflisting}
607 \begin{alltt}
608 10\$: \DWTAGarraytype
609         \DWATordering(\DWORDcolmajor)
610         \DWATtype(reference to INTEGER)
611 11\$:    \DWTAGsubrangetype
612             \DWATlowerbound(constant 1)
613             \DWATupperbound(constant 10)
614
615 12\$: \DWTAGcoarraytype
616         \DWATtype(reference to array type at 10\$)
617 13\$:    \DWTAGsubrangetype                ! Note omitted upper bound
618             \DWATlowerbound(constant 1)
619
620 14$: \DWTAGvariable
621         \DWATname("X")
622         \DWATtype(reference to coarray type at 12\$)
623 \end{alltt}
624 \end{dwflisting}
625 \caption{Fortran array coarray: DWARF description}
626 \label{fig:FortranarraycoarrayDWARFdescription}
627 \end{figure}
628
629 \subsubsection{Fortran Multidimensional Coarray Example}
630 The \addtoindex{Fortran} multidimensional coarray of a multidimensional array example
631 \addtoindexx{coarray!example}\addtoindexx{array coarray|see{coarray}}
632 in Figure \refersec{fig:Fortranmultidimensionalcoarraysourcefragment} can be described as 
633 illustrated in Figure \refersec{fig:FortranmultidimensionalcoarrayDWARFdescription}.
634
635 \begin{figure}[here]
636 \begin{lstlisting}
637         INTEGER X(10,11,12)[2,3,*]
638 \end{lstlisting}
639 \caption{Fortran multidimentional coarray: source fragment}
640 \label{fig:Fortranmultidimensionalcoarraysourcefragment}
641 \end{figure}
642
643 \begin{figure}[here]
644 \begin{dwflisting}
645 \begin{alltt}
646 10\$: \DWTAGarraytype
647         \DWATordering(\DWORDcolmajor)
648         \DWATtype(reference to INTEGER)
649 11\$:    \DWTAGsubrangetype
650             \DWATlowerbound(constant 1)
651             \DWATupperbound(constant 10)
652 12\$:    \DWTAGsubrangetype
653             \DWATlowerbound(constant  1)
654             \DWATupperbound(constant 11)
655 13\$:    \DWTAGsubrangetype
656             \DWATlowerbound(constant  1)
657             \DWATupperbound(constant 12)
658
659 14\$: \DWTAGcoarraytype
660         \DWATtype(reference to array_type at 10\$)
661 15\$:    \DWTAGsubrangetype
662             \DWATlowerbound(constant 1)
663             \DWATupperbound(constant 2)
664 16\$:    \DWTAGsubrangetype
665             \DWATlowerbound(constant 1)
666             \DWATupperbound(constant 3)
667 17\$:    \DWTAGsubrangetype                ! Note omitted upper bound
668             \DWATlowerbound(constant 1)
669
670 18\$: \DWTAGvariable
671         \DWATname("X")
672         \DWATtype(reference to coarray type at 14\$)
673 \end{alltt}
674 \end{dwflisting}
675 \caption{Fortran multidimensional coarray: DWARF description}
676 \label{fig:FortranmultidimensionalcoarrayDWARFdescription}
677 \end{figure}
678
679
680 \clearpage
681 \subsection{Fortran 2008 Assumed-rank Array Example}
682 \label{app:assumedrankexample}
683 \addtoindexx{array!assumed-rank}
684 Consider the example in Figure~\ref{fig:assumedrankdecl}, which shows
685 an assumed-rank array in Fortran~2008 with
686 supplement~29113:\footnote{Technical Specification ISO/IEC TS
687   29113:2012 \emph{Further Interoperability of Fortran with C}}
688
689 \begin{figure}[!h]
690 \begin{lstlisting}
691   subroutine foo(x)
692     real :: x(..)
693
694     ! x has n dimensions
695   
696   end subroutine
697 \end{lstlisting}
698 \caption{Declaration of a Fortran 2008 assumed-rank array}
699 \label{fig:assumedrankdecl}
700 \end{figure}
701
702 Let's assume the Fortran compiler used an array descriptor that
703 (in \addtoindex{C}) looks
704 like the one shown in Figure~\ref{fig:arraydesc}.
705
706 \begin{figure}[!h]
707 \begin{lstlisting}
708   struct array_descriptor {
709     void *base_addr;
710     int rank;
711     struct dim dims[]; 
712   }
713
714   struct dim {
715      int lower_bound;
716      int upper_bound;
717      int stride;
718      int flags;
719   }
720 \end{lstlisting}
721 \caption{One of many possible layouts for an array descriptor}
722 \label{fig:arraydesc}
723 \end{figure}
724
725 The DWARF type for the array \emph{x} can be described as shown in
726 Figure~\refersec{fig:assumedrankdwarf}.
727
728 \begin{figure}[!h]
729 \begin{dwflisting}
730 \begin{alltt}
731 10\$:  \DWTAGarraytype
732          \DWATtype(reference to real)
733          \DWATrank(expression=
734              \DWOPpushobjectaddress
735              \DWOPlitn                        ! offset of rank in descriptor
736              \DWOPplus
737              \DWOPderef)
738          \DWATdatalocation(expression=
739              \DWOPpushobjectaddress
740              \DWOPlitn                        ! offset of data in descriptor
741              \DWOPplus
742              \DWOPderef)
743 11\$:    \DWTAGgenericsubrange
744              \DWATtype(reference to integer)
745              \DWATlowerbound(expression=
746              !   Looks up the lower bound of dimension i.
747              !   Operation                       ! Stack effect
748              !   (implicit)                      ! i                                                                     
749                  \DWOPlitn                    ! i sizeof(dim)
750                  \DWOPmul                       ! dim[i]
751                  \DWOPlitn                    ! dim[i] offsetof(dim)
752                  \DWOPplus                      ! dim[i]+offset
753                  \DWOPpushobjectaddress       ! dim[i]+offsetof(dim) objptr
754                  \DWOPplus                      ! objptr.dim[i]
755                  \DWOPlitn                    ! objptr.dim[i] offsetof(lb)
756                  \DWOPplus                      ! objptr.dim[i].lowerbound
757                  \DWOPderef)                    ! *objptr.dim[i].lowerbound
758              \DWATupperbound(expression=
759              !   Looks up the upper bound of dimension i.
760                  \DWOPlitn                    ! sizeof(dim)
761                  \DWOPmul
762                  \DWOPlitn                    ! offsetof(dim)
763                  \DWOPplus
764                  \DWOPpushobjectaddress
765                  \DWOPplus
766                  \DWOPlitn                    ! offset of upperbound in dim
767                  \DWOPplus
768                  \DWOPderef)
769              \DWATbytestride(expression=
770              !   Looks up the byte stride of dimension i.
771                  ...
772              !   (analogous to \DWATupperboundNAME)
773                  )
774 \end{alltt}
775 \end{dwflisting}
776 \caption{Sample DWARF for the array descriptor in Figure~\ref{fig:arraydesc}}
777 \label{fig:assumedrankdwarf}
778 \end{figure}
779
780 The layout of the array descriptor is not specified by the Fortran
781 standard unless the array is explicitly marked as \addtoindex{C-interoperable}. To
782 get the bounds of an assumed-rank array, the expressions in the
783 \DWTAGgenericsubrange{}
784 entry need to be evaluated for each of the
785 \DWATrank{} dimensions as shown by the pseudocode in
786 Figure~\refersec{fig:assumedrankdwarfparser}.
787
788 \begin{figure}[!h]
789 \begin{lstlisting}
790     typedef struct {
791         int lower, upper, stride;
792     } dims_t;
793
794     typedef struct {
795         int rank;
796     struct dims_t *dims;
797     } array_t;
798
799     array_t get_dynamic_array_dims(DW_TAG_array a) {
800       array_t result;
801
802       // Evaluate the DW_AT_rank expression to get the 
803       //    number of dimensions.
804       dwarf_stack_t stack;
805       dwarf_eval(stack, a.rank_expr);
806       result.rank = dwarf_pop(stack); 
807       result.dims = new dims_t[rank];
808
809       // Iterate over all dimensions and find their bounds.
810       for (int i = 0; i < result.rank; i++) {
811         // Evaluate the generic subrange's DW_AT_lower 
812         //    expression for dimension i.
813         dwarf_push(stack, i);
814         assert( stack.size == 1 );
815         dwarf_eval(stack, a.generic_subrange.lower_expr);
816         result.dims[i].lower = dwarf_pop(stack);
817         assert( stack.size == 0 );
818
819         dwarf_push(stack, i);
820         dwarf_eval(stack, a.generic_subrange.upper_expr);
821         result.dims[i].upper = dwarf_pop(stack);
822     
823         dwarf_push(stack, i);
824         dwarf_eval(stack, a.generic_subrange.byte_stride_expr);
825         result.dims[i].stride = dwarf_pop(stack);
826       }
827       return result;
828     }
829 \end{lstlisting}
830 \caption{How to interpret the DWARF from Figure~\ref{fig:assumedrankdwarf}}
831 \label{fig:assumedrankdwarfparser}
832 \end{figure}
833
834
835
836 \clearpage
837 \subsection{Ada Example}
838 \label{app:adaexample}
839 Figure \refersec{fig:adaexamplesourcefragment}
840 illustrates two kinds of \addtoindex{Ada} 
841 parameterized array, one embedded in a record.
842
843 \begin{figure}[here]
844 \begin{lstlisting}
845 M : INTEGER := <exp>;
846 VEC1 : array (1..M) of INTEGER;
847 subtype TEENY is INTEGER range 1..100;
848 type ARR is array (INTEGER range <>) of INTEGER;
849 type REC2(N : TEENY := 100) is record
850     VEC2 : ARR(1..N);
851 end record;
852
853 OBJ2B : REC2;
854 \end{lstlisting}
855 \caption{Ada example: source fragment}
856 \label{fig:adaexamplesourcefragment}
857 \end{figure}
858
859 \texttt{VEC1} illustrates an (unnamed) array type where the upper bound
860 of the first and only dimension is determined at runtime. 
861 \addtoindex{Ada}
862 semantics require that the value of an array bound is fixed at
863 the time the array type is elaborated (where \textit{elaboration} refers
864 to the runtime executable aspects of type processing). For
865 the purposes of this example, we assume that there are no
866 other assignments to \texttt{M} so that it safe for the \texttt{REC1} type
867 description to refer directly to that variable (rather than
868 a compiler-generated copy).
869
870 \texttt{REC2} illustrates another array type (the unnamed type of
871 component \texttt{VEC2}) where the upper bound of the first and only
872 bound is also determined at runtime. In this case, the upper
873 bound is contained in a discriminant of the containing record
874 type. (A \textit{discriminant} is a component of a record whose value
875 cannot be changed independently of the rest of the record
876 because that value is potentially used in the specification
877 of other components of the record.)
878
879 The DWARF description is shown in 
880 Figure \refersec{fig:adaexampledwarfdescription}.
881
882
883 Interesting aspects about this example are:
884 \begin{enumerate}[1. ]
885 \item The array \texttt{VEC2} is \doublequote{immediately} contained within structure
886 \texttt{REC2} (there is no intermediate descriptor or indirection),
887 which is reflected in the absence of a \DWATdatalocation{}
888 attribute on the array type at 28\$.
889
890 \item One of the bounds of \texttt{VEC2} is nonetheless dynamic and part of
891 the same containing record. It is described as a reference to
892 a member, and the location of the upper bound is determined
893 as for any member. That is, the location is determined using
894 an address calculation relative to the base of the containing
895 object.  
896
897 A consumer must notice that the referenced bound is a
898 member of the same containing object and implicitly push the
899 base address of the containing object just as for accessing
900 a data member generally.
901
902 \item The lack of a subtype concept in DWARF means that DWARF types
903 serve the role of subtypes and must replicate information from
904 what should be the parent type. For this reason, DWARF for
905 the unconstrained array type \texttt{ARR} is not needed for the purposes
906 of this example and therefore is not shown.
907 \end{enumerate}
908
909 \begin{figure}[p]
910 \begin{dwflisting}
911 \begin{alltt}
912 11\$: \DWTAGvariable
913         \DWATname("M")
914         \DWATtype(reference to INTEGER)
915 12\$: \DWTAGarraytype
916         ! No name, default (\addtoindex{Ada}) order, default stride
917         \DWATtype(reference to INTEGER)
918 13\$:    \DWTAGsubrangetype
919             \DWATtype(reference to INTEGER)
920             \DWATlowerbound(constant 1)
921             \DWATupperbound(reference to variable M at 11\$)
922 14\$: \DWTAGvariable
923         \DWATname("VEC1")
924         \DWATtype(reference to array type at 12\$)
925      . . .
926 21\$: \DWTAGsubrangetype
927         \DWATname("TEENY")
928         \DWATtype(reference to INTEGER)
929         \DWATlowerbound(constant 1)
930         \DWATupperbound(constant 100)
931      . . .
932 26\$: \DWTAGstructuretype
933         \DWATname("REC2")
934 27\$:    \DWTAGmember
935             \DWATname("N")
936             \DWATtype(reference to subtype TEENY at 21\$)
937             \DWATdatamemberlocation(constant 0)
938 28\$:    \DWTAGarraytype
939             ! No name, default (\addtoindex{Ada}) order, default stride
940             ! Default data location
941             \DWATtype(reference to INTEGER)
942 29\$:        \DWTAGsubrangetype
943                 \DWATtype(reference to subrange TEENY at 21\$)
944                 \DWATlowerbound(constant 1)
945                 \DWATupperbound(reference to member N at 27\$)
946 30\$:    \DWTAGmember
947             \DWATname("VEC2")
948             \DWATtype(reference to array "subtype" at 28\$)
949             \DWATdatamemberlocation(machine=
950                 \DWOPlitn                  ! where n == offset(REC2, VEC2)
951                 \DWOPplus)
952      . . .
953 41\$: \DWTAGvariable
954         \DWATname("OBJ2B")
955         \DWATtype(reference to REC2 at 26\$)
956         \DWATlocation(...as appropriate...)
957 \end{alltt}
958 \end{dwflisting}
959 \caption{Ada example: DWARF description}
960 \label{fig:adaexampledwarfdescription}
961 \end{figure}
962
963 \clearpage
964
965 \subsection{Pascal Example}
966 \label{app:pascalexample}
967 The Pascal \addtoindexx{Pascal example} source in 
968 Figure \referfol{fig:packedrecordexamplesourcefragment}
969 is used to illustrate the representation of packed unaligned
970 \addtoindex{bit fields}.
971
972 \begin{figure}[here]
973 \begin{lstlisting}
974 TYPE T : PACKED RECORD                  ! bit size is 2
975          F5 : BOOLEAN;                  ! bit offset is 0
976          F6 : BOOLEAN;                  ! bit offset is 1
977          END;
978 VAR V :  PACKED RECORD
979          F1 : BOOLEAN;                  ! bit offset is 0
980          F2 : PACKED RECORD             ! bit offset is 1
981               F3 : INTEGER;             ! bit offset is 0 in F2, 1 in V
982               END;
983          F4 : PACKED ARRAY [0..1] OF T; ! bit offset is 33
984          F7 : T;                        ! bit offset is 37
985          END;
986 \end{lstlisting}
987 \caption{Packed record example: source fragment}
988 \label{fig:packedrecordexamplesourcefragment}
989 \end{figure}
990
991 The DWARF representation in 
992 Figure \refersec{fig:packedrecordexampledwarfdescription} 
993 is appropriate. 
994 \DWTAGpackedtype{} entries could be added to
995 better represent the source, but these do not otherwise affect
996 the example and are omitted for clarity. Note that this same
997 representation applies to both typical big\dash \ and 
998 little\dash endian
999 architectures using the conventions described in 
1000 Section \refersec{chap:datamemberentries}.
1001
1002 \begin{figure}[h]
1003 \figurepart{1}{2}
1004 \begin{dwflisting}
1005 \begin{alltt}
1006 10\$: \DWTAGbasetype
1007         \DWATname("BOOLEAN")
1008             ...
1009 11\$: \DWTAGbasetype
1010         \DWATname("INTEGER")
1011             ...
1012 20\$: \DWTAGstructuretype
1013         \DWATname("T")
1014         \DWATbitsize(2)
1015         \DWTAGmember
1016             \DWATname("F5")
1017             \DWATtype(reference to 10$)
1018             \DWATdatabitoffset(0)        ! may be omitted
1019             \DWATbitsize(1)
1020 \end{alltt}
1021 \end{dwflisting}
1022 \caption{Packed record example: DWARF description}
1023 \label{fig:packedrecordexampledwarfdescription}
1024 \end{figure}
1025
1026 \begin{figure}[h]
1027 \figurepart{2}{2}
1028 \begin{dwflisting}
1029 \begin{alltt}
1030         \DWTAGmember
1031             \DWATname("F6")
1032             \DWATtype(reference to 10$)
1033             \DWATdatabitoffset(1)
1034             \DWATbitsize(1)
1035 21\$: \DWTAGstructuretype                  ! anonymous type for F2
1036         \DWTAGmember
1037             \DWATname("F3")
1038             \DWATtype(reference to 11\$)
1039 22\$: \DWTAGarraytype                      ! anonymous type for F4
1040         \DWATtype(reference to 20\$)
1041         \DWTAGsubrangetype
1042             \DWATtype(reference to 11\$)
1043             \DWATlowerbound(0)
1044             \DWATupperbound(1)
1045         \DWATbitstride(2)
1046         \DWATbitsize(4) \addtoindexx{bit size attribute}
1047 23\$: \DWTAGstructuretype                  ! anonymous type for V
1048         \DWATbitsize(39) \addtoindexx{bit size attribute}
1049         \DWTAGmember
1050             \DWATname("F1")
1051             \DWATtype(reference to 10\$)
1052             \DWATdatabitoffset(0)        ! may be omitted
1053             \DWATbitsize(1) ! may be omitted
1054         \DWTAGmember
1055             \DWATname("F2")
1056             \DWATtype(reference to 21\$)
1057             \DWATdatabitoffset(1)
1058             \DWATbitsize(32) ! may be omitted
1059         \DWTAGmember
1060             \DWATname("F4")
1061             \DWATtype(reference to 22\$)
1062             \DWATdatabitoffset(33)
1063             \DWATbitsize(4) ! may be omitted
1064         \DWTAGmember
1065             \DWATname("F7")
1066             \DWATtype(reference to 20\$)    ! type T
1067             \DWATdatabitoffset(37)
1068             \DWATbitsize(2) \addtoindexx{bit size attribute}              ! may be omitted
1069      \DWTAGvariable
1070         \DWATname("V")
1071         \DWATtype(reference to 23\$)
1072         \DWATlocation(...)
1073         ...
1074 \end{alltt}
1075 \end{dwflisting}
1076 \begin{center}
1077 Figure~\ref{fig:packedrecordexampledwarfdescription}: Packed record example: DWARF description \textit{(concluded)}
1078 \end{center}
1079 \end{figure}
1080
1081 \clearpage
1082 \subsection{Fortran Dynamic Type Example}
1083 \label{app:fortrandynamictypeexample}
1084 Consider the \addtoindex{Fortran 90} example of dynamic properties in 
1085 Figure \refersec{fig:fortrandynamictypeexamplesource}.
1086 This can be represented in DWARF as illustrated in 
1087 Figure \refersec{fig:fortrandynamictypeexampledwarfdescription}.
1088 Note that unnamed dynamic types are used to avoid replicating
1089 the full description of the underlying type \texttt{dt} that is shared by
1090 several variables.
1091
1092 \begin{figure}[h]
1093 \begin{lstlisting}
1094             program sample
1095      
1096         type :: dt (l)
1097             integer, len :: l
1098             integer :: arr(l)
1099         end type
1100
1101         integer :: n = 4
1102         contains
1103
1104         subroutine s()
1105             type (dt(n))               :: t1
1106             type (dt(n)), pointer      :: t2
1107             type (dt(n)), allocatable  :: t3, t4
1108         end subroutine
1109      
1110         end sample
1111 \end{lstlisting}
1112 \caption{Fortran dynamic type example: source}
1113 \label{fig:fortrandynamictypeexamplesource}
1114 \end{figure}
1115
1116 \begin{figure}[h]
1117 \begin{dwflisting}
1118 \begin{alltt}
1119 11$:    \DWTAGstructuretype
1120             \DWATname("dt")
1121             \DWTAGmember
1122                 ...
1123                         ...
1124
1125 13$:    \DWTAGdynamictype             ! plain version
1126             \DWATdatalocation (dwarf expression to locate raw data)
1127             \DWATtype (11$)
1128
1129 14$:    \DWTAGdynamictype             ! 'pointer' version
1130             \DWATdatalocation (dwarf expression to locate raw data)
1131             \DWATassociated (dwarf expression to test if associated)
1132             \DWATtype (11$)
1133
1134 15$:    \DWTAGdynamictype             ! 'allocatable' version
1135             \DWATdatalocation (dwarf expression to locate raw data)
1136             \DWATallocated (dwarf expression to test is allocated)
1137             \DWATtype (11$)
1138
1139 16$:    \DWTAGvariable
1140             \DWATname ("t1")
1141             \DWATtype (13$)
1142             \DWATlocation (dwarf expression to locate descriptor)
1143 17$:    \DWTAGvariable
1144             \DWATname ("t2")
1145             \DWATtype (14$)
1146             \DWATlocation (dwarf expression to locate descriptor)
1147 18$:    \DWTAGvariable
1148             \DWATname ("t3")
1149             \DWATtype (15$)
1150             \DWATlocation (dwarf expression to locate descriptor)
1151 19$:    \DWTAGvariable
1152             \DWATname ("t4")
1153             \DWATtype (15$)
1154             \DWATlocation (dwarf expression to locate descriptor)
1155 \end{alltt}
1156 \end{dwflisting}
1157 \caption{Fortran dynamic type example: DWARF description}
1158 \label{fig:fortrandynamictypeexampledwarfdescription}
1159 \end{figure}
1160
1161 \clearpage
1162 \section{Namespace Example}
1163 \label{app:namespaceexample}
1164
1165 The \addtoindex{C++} example in 
1166 Figure \refersec{fig:namespaceexamplesourcefragment}
1167 is used 
1168 \addtoindexx{namespace (C++)!example}
1169 to illustrate the representation of namespaces.
1170 The DWARF representation in 
1171 Figure \refersec{fig:namespaceexampledwarfdescription}
1172 is appropriate.
1173
1174 \begin{figure}[h]
1175 \begin{lstlisting}
1176 namespace {
1177     int i;
1178 }
1179 namespace A {
1180     namespace B {
1181         int j;
1182         int   myfunc (int a);
1183         float myfunc (float f) { return f - 2.0; }
1184         int   myfunc2(int a)   { return a + 2; }
1185     }
1186 }
1187 namespace Y {
1188     using A::B::j;         // (1) using declaration
1189     int foo;
1190 }
1191 using A::B::j;             // (2) using declaration
1192 namespace Foo = A::B;      // (3) namespace alias
1193 using Foo::myfunc;         // (4) using declaration
1194 using namespace Foo;       // (5) using directive
1195 namespace A {
1196     namespace B {
1197         using namespace Y; // (6) using directive
1198         int k;
1199     }
1200 }
1201 int Foo::myfunc(int a)
1202 {
1203     i = 3;
1204     j = 4;
1205     return myfunc2(3) + j + i + a + 2;
1206 }
1207 \end{lstlisting}
1208 \caption{Namespace example: source fragment}
1209 \label{fig:namespaceexamplesourcefragment}
1210 \end{figure}
1211
1212
1213 \begin{figure}[p]
1214 \figurepart{1}{2}
1215 \begin{dwflisting}
1216 \begin{alltt}
1217
1218 1\$:  \DWTAGbasetype
1219         \DWATname("int")
1220         ...
1221 2\$:  \DWTAGbasetype
1222         \DWATname("float")
1223         ...
1224 6\$:  \DWTAGnamespace
1225         ! no \DWATname attribute
1226 7\$:
1227         \DWTAGvariable
1228             \DWATname("i")
1229             \DWATtype(reference to 1\$)
1230             \DWATlocation ...
1231             ...
1232 10\$: \DWTAGnamespace
1233         \DWATname("A")
1234 20\$:    \DWTAGnamespace
1235             \DWATname("B")
1236 30\$:        \DWTAGvariable
1237                 \DWATname("j")
1238                 \DWATtype(reference to 1\$)
1239                 \DWATlocation ...
1240                 ...
1241 34\$:        \DWTAGsubprogram
1242                 \DWATname("myfunc")
1243                 \DWATtype(reference to 1\$)
1244                 ...
1245 36\$:        \DWTAGsubprogram
1246                 \DWATname("myfunc")
1247                 \DWATtype(reference to 2\$)
1248                 ...
1249 38\$:        \DWTAGsubprogram
1250                 \DWATname("myfunc2")
1251                 \DWATlowpc ...
1252                 \DWAThighpc ...
1253                 \DWATtype(reference to 1\$)
1254                 ...
1255 \end{alltt}
1256 \end{dwflisting}
1257 \caption{Namespace example: DWARF description}
1258 \label{fig:namespaceexampledwarfdescription}
1259 \end{figure}
1260
1261 \begin{figure}
1262 \figurepart{2}{2}
1263 \begin{dwflisting}
1264 \begin{alltt}
1265 40\$: \DWTAGnamespace
1266         \DWATname("Y")
1267         \DWTAGimporteddeclaration            ! (1) using-declaration
1268             \DWATimport(reference to 30\$)
1269         \DWTAGvariable
1270             \DWATname("foo")
1271             \DWATtype(reference to 1\$)
1272             \DWATlocation ...
1273             ...
1274      \DWTAGimporteddeclaration               ! (2) using declaration
1275         \DWATimport(reference to 30\$)
1276         \DWTAGimporteddeclaration            ! (3) namespace alias
1277             \DWATname("Foo")
1278             \DWATimport(reference to 20\$)
1279         \DWTAGimporteddeclaration            ! (4) using declaration
1280             \DWATimport(reference to 34\$)     !     - part 1
1281         \DWTAGimporteddeclaration            ! (4) using declaration
1282             \DWATimport(reference to 36\$)     !     - part 2
1283         \DWTAGimportedmodule                 ! (5) using directive
1284             \DWATimport(reference to 20\$)
1285         \DWTAGnamespace
1286             \DWATextension(reference to 10\$)
1287             \DWTAGnamespace
1288                 \DWATextension(reference to 20\$)
1289                 \DWTAGimportedmodule         ! (6) using directive
1290                     \DWATimport(reference to 40\$)
1291                 \DWTAGvariable
1292                     \DWATname("k")
1293                     \DWATtype(reference to 1\$)
1294                     \DWATlocation ...
1295                     ...
1296 60\$: \DWTAGsubprogram
1297         \DWATspecification(reference to 34\$)
1298         \DWATlowpc ...
1299         \DWAThighpc ...
1300         ...
1301 \end{alltt}
1302 \end{dwflisting}
1303 \begin{center}
1304 Figure~\ref{fig:namespaceexampledwarfdescription}: Namespace example: DWARF description \textit{(concluded)}
1305 \end{center}
1306 \end{figure}
1307
1308 \clearpage
1309 \section{Member Function Examples}
1310 \label{app:memberfunctionexample}
1311
1312 Consider the member function example fragment in 
1313 Figure \refersec{fig:memberfunctionexamplesourcefragment}.
1314 The DWARF representation in 
1315 Figure \refersec{fig:memberfunctionexampledwarfdescription}
1316 is appropriate.
1317
1318 \begin{figure}[h]
1319 \begin{lstlisting}
1320 class A
1321 {
1322     void func1(int x1);
1323     void func2() const;
1324     static void func3(int x3);
1325 };
1326 void A::func1(int x) {}
1327 \end{lstlisting}
1328 \caption{Member function example: source fragment}
1329 \label{fig:memberfunctionexamplesourcefragment}
1330 \end{figure}
1331
1332 \begin{figure}[h]
1333 \figurepart{1}{2}
1334 \begin{dwflisting}
1335 \begin{alltt}
1336 1\$: \DWTAGunspecifiedtype
1337         \DWATname("void")
1338                 ...
1339 2\$: \DWTAGbasetype
1340         \DWATname("int")
1341         ...
1342 3\$: \DWTAGclasstype
1343         \DWATname("A")
1344         ...
1345 4\$:    \DWTAGpointertype
1346             \DWATtype(reference to 3\$)
1347             ...
1348 5\$:    \DWTAGconsttype
1349             \DWATtype(reference to 3\$)
1350             ...
1351 6\$:    \DWTAGpointertype
1352             \DWATtype(reference to 5\$)
1353             ...
1354
1355 7\$:    \DWTAGsubprogram
1356             \DWATdeclaration
1357             \DWATname("func1")
1358             \DWATtype(reference to 1\$)
1359             \DWATobjectpointer(reference to 8\$) \addtoindexx{object pointer attribute}
1360                 ! References a formal parameter in this 
1361                 ! member function
1362             ...
1363 \end{alltt}
1364 \end{dwflisting}
1365 \caption{Member function example: DWARF description}
1366 \label{fig:memberfunctionexampledwarfdescription}
1367 \end{figure}
1368
1369 \begin{figure}[p]
1370 \figurepart{2}{2}
1371 \begin{dwflisting}
1372 \begin{alltt}
1373 8\$:        \DWTAGformalparameter
1374                 \DWATartificial(true)
1375                 \DWATname("this")
1376                 \DWATtype(reference to 4\$)
1377                     ! Makes type of 'this' as 'A*' =>
1378                     ! func1 has not been marked const 
1379                     ! or volatile
1380                 \DWATlocation ...
1381                 ...
1382 9\$:        \DWTAGformalparameter
1383                 \DWATname(x1)
1384                 \DWATtype(reference to 2\$)
1385                 ...
1386 10\$:    \DWTAGsubprogram
1387              \DWATdeclaration
1388              \DWATname("func2")
1389              \DWATtype(reference to 1\$)
1390              \DWATobjectpointer(reference to 11\$) \addtoindexx{object pointer attribute}
1391              ! References a formal parameter in this 
1392              ! member function
1393              ...
1394 11\$:        \DWTAGformalparameter
1395                  \DWATartificial(true)
1396                  \DWATname("this")
1397                  \DWATtype(reference to 6\$)
1398                  ! Makes type of 'this' as 'A const*' =>
1399                  !     func2 marked as const
1400                  \DWATlocation ...
1401                  ...
1402 12\$:    \DWTAGsubprogram
1403              \DWATdeclaration
1404              \DWATname("func3")
1405              \DWATtype(reference to 1\$)
1406              ...
1407                  ! No object pointer reference formal parameter
1408                  ! implies func3 is static
1409 13\$:        \DWTAGformalparameter
1410                  \DWATname(x3)
1411                  \DWATtype(reference to 2\$)
1412                  ...
1413 \end{alltt}
1414 \end{dwflisting}
1415 \begin{center}
1416 Figure~\ref{fig:memberfunctionexampledwarfdescription}: Member function example: DWARF description \textit{(concluded)}
1417 \end{center}
1418 \end{figure}
1419
1420 As a further example illustrating \&- and \&\&-qualification, 
1421 consider the member function example fragment in 
1422 Figure \refersec{fig:memberfunctionrefqualexamplesourcefragment}.
1423 The DWARF representation in 
1424 Figure \refersec{fig:memberfunctionrefqualexampledwarfdescription}
1425 is appropriate.
1426
1427 \begin{figure}[h]
1428 \begin{lstlisting}
1429 class A {
1430 public:
1431     void f() const &&;
1432 };
1433    
1434 void g() {
1435     A a;
1436     // The type of pointer is "void (A::*)() const &&".
1437     auto pointer = &A::f;
1438 }
1439 \end{lstlisting}
1440 \caption{Member function with reference-qualification example: source \mbox{fragment}}
1441 \label{fig:memberfunctionrefqualexamplesourcefragment}
1442 \end{figure}
1443
1444 \begin{figure}[h]
1445 %\figurepart{1}{2}
1446 \begin{dwflisting}
1447 \begin{alltt}
1448
1449 ... to be provided...
1450
1451 \end{alltt}
1452 \end{dwflisting}
1453 \caption{Member function with reference-qualification example: DWARF \mbox{description}}
1454 \label{fig:memberfunctionrefqualexampledwarfdescription}
1455 \end{figure}
1456
1457
1458 \clearpage
1459 \section{Line Number Program Example}
1460 \label{app:linenumberprogramexample}
1461
1462 Consider the simple source file and the resulting machine
1463 code for the Intel 8086 processor in 
1464 Figure \refersec{fig:linenumberprogramexamplemachinecode}.
1465
1466 \begin{figure}[here]
1467 \begin{lstlisting}
1468 1: int
1469 2: main()
1470     0x239: push pb
1471     0x23a: mov bp,sp
1472 3: {
1473 4: printf("Omit needless words\n");
1474     0x23c: mov ax,0xaa
1475     0x23f: push ax
1476     0x240: call _printf
1477     0x243: pop cx
1478 5: exit(0);
1479     0x244: xor ax,ax
1480     0x246: push ax
1481     0x247: call _exit
1482     0x24a: pop cx
1483 6: }
1484     0x24b: pop bp
1485     0x24c: ret
1486 7: 0x24d:
1487 \end{lstlisting}
1488 \caption{Line number program example: machine code}
1489 \label{fig:linenumberprogramexamplemachinecode}
1490 \end{figure}
1491
1492 Suppose the line number program header includes the following
1493 (header fields not needed 
1494 \addtoindexx{line\_base}
1495 below 
1496 \addtoindexx{line\_range}
1497 are 
1498 \addtoindexx{opcode\_base}
1499 not 
1500 \addtoindexx{minumum\_instruction\_length}
1501 shown):
1502 \begin{alltt}
1503     version                       4
1504     minimum_instruction_length    1
1505     opcode_base                  10   ! Opcodes 10-12 not needed
1506     line_base                     1
1507     line_range                   15
1508 \end{alltt}
1509
1510
1511 Table \refersec{tab:linenumberprogramexampleoneencoding}
1512 shows one encoding of the line number program, which occupies
1513 12 bytes (the opcode SPECIAL(\textit{m},\textit{n}) indicates the special opcode
1514 generated for a line increment of \textit{m} and an address increment
1515 of \textit{n}).
1516
1517 \newpage
1518 \begin{centering}
1519 \setlength{\extrarowheight}{0.1cm}
1520 \begin{longtable}{l|l|l}
1521   \caption{Line number program example: one \mbox{encoding}}
1522   \label{tab:linenumberprogramexampleoneencoding} \\
1523   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
1524 \endfirsthead
1525   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
1526 \endhead
1527   \hline \emph{Continued on next page}
1528 \endfoot
1529   \hline
1530 \endlastfoot
1531 \DWLNSadvancepc&LEB128(0x239)&0x2, 0xb9, 0x04 \\
1532 SPECIAL(2, 0)& &0xb  \\
1533 SPECIAL(2, 3)& &0x38 \\
1534 SPECIAL(1, 8)& &0x82 \\
1535 SPECIAL(1, 7)& &0x73 \\
1536 \DWLNSadvancepc&LEB128(2)&0x2, 0x2 \\
1537 \DWLNEendsequence{} &&0x0, 0x1, 0x1 \\
1538 \end{longtable}
1539 \end{centering}
1540
1541
1542 Table \refersec{tab:linenumberprogramexamplealternateencoding}
1543 shows an alternate 
1544 encoding of the same program using 
1545 standard opcodes to advance
1546 the program counter; 
1547 this encoding occupies 22 bytes.
1548
1549 \begin{centering}
1550 \setlength{\extrarowheight}{0.1cm}
1551 \begin{longtable}{l|l|l}
1552   \caption{Line number program example: alternate encoding} 
1553   \label{tab:linenumberprogramexamplealternateencoding} \\
1554   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
1555 \endfirsthead
1556   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
1557 \endhead
1558   \hline \emph{Continued on next page}
1559 \endfoot
1560   \hline
1561 \endlastfoot
1562 \DWLNSfixedadvancepc&0x239&0x9, 0x39, 0x2        \\
1563 SPECIAL(2, 0)&& 0xb        \\
1564 \DWLNSfixedadvancepc&0x3&0x9, 0x3, 0x0        \\
1565 SPECIAL(2, 0)&&0xb        \\
1566 \DWLNSfixedadvancepc&0x8&0x9, 0x8, 0x0        \\
1567 SPECIAL(1, 0)&& 0xa        \\
1568 \DWLNSfixedadvancepc&0x7&0x9, 0x7, 0x0        \\
1569 SPECIAL(1, 0) && 0xa        \\
1570 \DWLNSfixedadvancepc&0x2&0x9, 0x2, 0x0        \\
1571 \DWLNEendsequence&&0x0, 0x1, 0x1        \\
1572 \end{longtable}
1573 \end{centering}
1574
1575 \needlines{6}
1576 \section{Call Frame Information Example}
1577 \label{app:callframeinformationexample}
1578
1579 The following example uses a hypothetical RISC machine in
1580 the style of the Motorola 88000.
1581 \begin{itemize}
1582 \item Memory is byte addressed.
1583
1584 \item Instructions are all 4 bytes each and word aligned.
1585
1586 \item Instruction operands are typically of the form:
1587 \begin{alltt}
1588     <destination.reg>, <source.reg>, <constant>
1589 \end{alltt}
1590
1591 \item The address for the load and store instructions is computed
1592 by adding the contents of the
1593 source register with the constant.
1594
1595 \item There are eight 4\dash byte registers:
1596 \newline
1597 \begin{tabular}{p{5mm}l}
1598    & R0 always 0 \\
1599    & R1 holds return address on call \\
1600    & R2-R3 temp registers (not preserved on call) \\
1601    & R4-R6 preserved on call \\
1602    & R7 stack pointer \\
1603 \end{tabular}
1604
1605 \item  The stack grows in the negative direction.
1606
1607 \item The architectural ABI committee specifies that the
1608 stack pointer (R7) is the same as the CFA
1609
1610 \end{itemize}
1611
1612 Figure \referfol{fig:callframeinformationexamplemachinecodefragments}
1613 shows two code fragments from a subroutine called
1614 foo that uses a frame pointer (in addition to the stack
1615 pointer). The first column values are byte addresses. 
1616 % The \space is so we get a space after >
1617 \textless fs\textgreater\ denotes the stack frame size in bytes, namely 12.
1618
1619
1620 \begin{figure}[here]
1621 \begin{lstlisting}
1622        ;; start prologue
1623 foo    sub   R7, R7, <fs>        ; Allocate frame
1624 foo+4  store R1, R7, (<fs>-4)    ; Save the return address
1625 foo+8  store R6, R7, (<fs>-8)    ; Save R6
1626 foo+12 add   R6, R7, 0           ; R6 is now the Frame ptr
1627 foo+16 store R4, R6, (<fs>-12)   ; Save a preserved reg
1628        ;; This subroutine does not change R5
1629        ...
1630        ;; Start epilogue (R7 is returned to entry value)
1631 foo+64 load  R4, R6, (<fs>-12)   ; Restore R4
1632 foo+68 load  R6, R7, (<fs>-8)    ; Restore R6
1633 foo+72 load  R1, R7, (<fs>-4)    ; Restore return address
1634 foo+76 add   R7, R7, <fs>        ; Deallocate frame
1635 foo+80 jump  R1                  ; Return
1636 foo+84
1637 \end{lstlisting}
1638 \caption{Call frame information example: machine code fragments}
1639 \label{fig:callframeinformationexamplemachinecodefragments}
1640 \end{figure}
1641
1642
1643 An abstract table 
1644 (see Section \refersec{chap:structureofcallframeinformation}) 
1645 for the foo subroutine is shown in 
1646 Table \referfol{tab:callframeinformationexampleconceptualmatrix}.
1647 Corresponding fragments from the
1648 \dotdebugframe{} section are shown in 
1649 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
1650
1651 The following notations apply in 
1652 Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
1653 \newline
1654 \begin{tabular}{p{5mm}l}
1655 &1.  R8 is the return address \\
1656 &2.  s = same\_value rule \\
1657 &3.  u = undefined rule \\
1658 &4.  rN = register(N) rule \\
1659 &5.  cN = offset(N) rule \\
1660 &6.  a = architectural rule \\
1661 \end{tabular}
1662
1663 \begin{centering}
1664 \setlength{\extrarowheight}{0.1cm}
1665 \begin{longtable}{l|llllllllll}
1666   \caption{Call frame information example: conceptual matrix} 
1667   \label{tab:callframeinformationexampleconceptualmatrix} \\
1668   \hline \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
1669 \endfirsthead
1670   \bfseries Location &\bfseries CFA &\bfseries R0 & \bfseries R1 & \bfseries R2 &\bfseries R3 &\bfseries R4 &\bfseries R5 &\bfseries R6 &\bfseries R7 &\bfseries R8\\ \hline
1671 \endhead
1672   \hline \emph{Continued on next page}
1673 \endfoot
1674   \hline
1675 \endlastfoot
1676 foo&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
1677 foo+4&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
1678 foo+8&[R7]+fs&s&u&u&u&s&s&s&a&c-4 \\
1679 foo+12&[R7]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
1680 foo+16&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
1681 foo+20&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
1682 ...&&&&&&&&&& \\
1683 foo+64&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
1684 foo+68&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4  \\
1685 foo+72&[R7]+fs&s&u&u&u&s&s&s&a&c-4  \\
1686 foo+76&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
1687 foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
1688 \end{longtable}
1689 \end{centering}
1690
1691 \clearpage      % ?????
1692
1693 \begin{centering}
1694 \setlength{\extrarowheight}{0.1cm}
1695 \begin{longtable}{l|ll}
1696   \caption{Call frame information example: common information entry encoding} 
1697   \label{tab:callframeinformationexamplecommoninformationentryencoding} 
1698   \\
1699   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1700 \endfirsthead
1701   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1702 \endhead
1703   \hline \emph{Continued on next page}
1704 \endfoot
1705   \hline
1706 \endlastfoot
1707 cie&36&length    \\
1708 cie+4&\xffffffff&CIE\_id    \\
1709 cie+8&4&version    \\
1710 cie+9&0&augmentation     \\
1711 cie+10&4&address size    \\
1712 cie+11&0&segment size    \\
1713 cie+12&4&code\_alignment\_factor, \textless caf \textgreater    \\
1714 cie+13&-4&data\_alignment\_factor, \textless daf \textgreater    \\
1715 cie+14&8&R8 is the return addr.    \\
1716 cie+15&\DWCFAdefcfa{} (7, 0)&CFA = [R7]+0    \\
1717 cie+18&\DWCFAsamevalue{} (0)&R0 not modified (=0)    \\
1718 cie+20&\DWCFAundefined{} (1)&R1 scratch    \\
1719 cie+22&\DWCFAundefined{} (2)&R2 scratch    \\
1720 cie+24&\DWCFAundefined{} (3)&R3 scratch    \\
1721 cie+26&\DWCFAsamevalue{} (4)&R4 preserve    \\
1722 cie+28&\DWCFAsamevalue{} (5)&R5 preserve    \\
1723 cie+30&\DWCFAsamevalue{} (6)&R6 preserve    \\
1724 cie+32&\DWCFAsamevalue{} (7)&R7 preserve    \\
1725 cie+34&\DWCFAregister{} (8, 1)&R8 is in R1    \\
1726 cie+37&\DWCFAnop{} &padding    \\
1727 cie+38&\DWCFAnop{} &padding \\
1728 cie+39& \DWCFAnop&padding  \\
1729 cie+40 &&  \\
1730 \end{longtable}
1731 \end{centering}
1732
1733
1734 The following notations apply in 
1735 Table \refersec{tab:callframeinformationexampleframedescriptionentryencoding}:
1736 \newline
1737 \begin{tabular}{p{5mm}l}
1738 &\texttt{<fs>  =} frame size \\
1739 &\texttt{<caf> =} code alignment factor \\
1740 &\texttt{<daf> =} data alignment factor \\
1741 \end{tabular}
1742
1743
1744 \begin{centering}
1745 \setlength{\extrarowheight}{0.1cm}
1746 \begin{longtable}{l|ll}
1747   \caption{Call frame information example: frame description entry encoding} 
1748   \label{tab:callframeinformationexampleframedescriptionentryencoding} \\
1749   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1750 \endfirsthead
1751   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1752 \endhead
1753   \hline \emph{Continued on next page}
1754 \endfoot
1755   \hline
1756 \endlastfoot
1757 fde&40&length \\
1758 fde+4&cie&CIE\_ptr \\
1759 fde+8&foo&initial\_location \\
1760 fde+12&84&address\_range \\
1761 fde+16&\DWCFAadvanceloc(1)&instructions \\
1762 fde+17&\DWCFAdefcfaoffset(12)& \textless fs\textgreater \\
1763 fde+19&\DWCFAadvanceloc(1)&4/\textless caf\textgreater \\
1764 fde+20&\DWCFAoffset(8,1)&-4/\textless daf\textgreater (2nd parameter) \\
1765 fde+22&\DWCFAadvanceloc(1)& \\
1766 fde+23&\DWCFAoffset(6,2)&-8/\textless daf\textgreater (2nd parameter)  \\
1767 fde+25&\DWCFAadvanceloc(1) & \\
1768 fde+26&\DWCFAdefcfaregister(6) & \\
1769 fde+28&\DWCFAadvanceloc(1) & \\
1770 fde+29&\DWCFAoffset(4,3)&-12/\textless daf\textgreater (2nd parameter) \\
1771 fde+31&\DWCFAadvanceloc(12)&44/\textless caf\textgreater \\
1772 fde+32&\DWCFArestore(4)& \\
1773 fde+33&\DWCFAadvanceloc(1) & \\
1774 fde+34&\DWCFArestore(6) & \\
1775 fde+35&\DWCFAdefcfaregister(7)  & \\
1776 fde+37&\DWCFAadvanceloc(1) & \\
1777 fde+38&\DWCFArestore(8) &\\
1778 fde+39&\DWCFAadvanceloc(1) &\\
1779 fde+40&\DWCFAdefcfaoffset(0)  &\\
1780 fde+42&\DWCFAnop&padding \\
1781 fde+43&\DWCFAnop&padding \\
1782 fde+44 && \\
1783 \end{longtable}
1784 \end{centering}
1785
1786 \section{Inlining Examples}
1787 \label{app:inliningexamples}
1788 The pseudo\dash source in 
1789 Figure \referfol{fig:inliningexamplespseudosourcefragment}
1790 is used to illustrate the
1791 \addtoindexx{inlined subprogram call!examples}
1792 use of DWARF to describe inlined subroutine calls. This
1793 example involves a nested subprogram \texttt{INNER} that makes uplevel
1794 references to the formal parameter and local variable of the
1795 containing subprogram \texttt{OUTER}.
1796
1797 \begin{figure}[here]
1798 \begin{lstlisting}
1799 inline procedure OUTER (OUTER_FORMAL : integer) =
1800     begin
1801     OUTER_LOCAL : integer;
1802     procedure INNER (INNER_FORMAL : integer) =
1803         begin
1804         INNER_LOCAL : integer;
1805         print(INNER_FORMAL + OUTER_LOCAL);
1806         end;
1807     INNER(OUTER_LOCAL);
1808     ...
1809     INNER(31);
1810     end;
1811 ! Call OUTER
1812 !
1813 OUTER(7);
1814 \end{lstlisting}
1815 \caption{Inlining examples: pseudo-source fragmment} 
1816 \label{fig:inliningexamplespseudosourcefragment}
1817 \end{figure}
1818
1819
1820 There are several approaches that a compiler might take to
1821 inlining for this sort of example. This presentation considers
1822 three such approaches, all of which involve inline expansion
1823 of subprogram \texttt{OUTER}. (If \texttt{OUTER} is not inlined, the inlining
1824 reduces to a simpler single level subset of the two level
1825 approaches considered here.)
1826
1827 The approaches are:
1828 \begin{enumerate}[1. ]
1829 \item  Inline both \texttt{OUTER} and \texttt{INNER} in all cases
1830
1831 \item Inline \texttt{OUTER}, multiple \texttt{INNER}s \\
1832 Treat \texttt{INNER} as a non\dash inlinable part of \texttt{OUTER}, compile and
1833 call a distinct normal version of \texttt{INNER} defined within each
1834 inlining of \texttt{OUTER}.
1835
1836 \item Inline \texttt{OUTER}, one \texttt{INNER} \\
1837 Compile \texttt{INNER} as a single normal subprogram which is called
1838 from every inlining of \texttt{OUTER}.
1839 \end{enumerate}
1840
1841 This discussion does not consider why a compiler might choose
1842 one of these approaches; it considers only how to describe
1843 the result.
1844
1845 In the examples that follow in this section, the debugging
1846 information entries are given mnemonic labels of the following
1847 form
1848 \begin{verbatim}
1849     <io>.<ac>.<n>.<s>
1850 \end{verbatim}
1851 where
1852 \begin{description}
1853 \item[\textless io\textgreater]
1854 is either \texttt{INNER} or \texttt{OUTER} to indicate to which
1855 subprogram the debugging information entry applies, 
1856 \item[\textless ac\textgreater]
1857 is either AI or CI to indicate \doublequote{abstract instance} or
1858 \doublequote{concrete instance} respectively, 
1859 \item[\textless n\textgreater]
1860 is the number of the
1861 alternative being considered, and 
1862 \item[\textless s\textgreater]
1863 is a sequence number that
1864 distinguishes the individual entries. 
1865 \end{description}
1866 There is no implication
1867 that symbolic labels, nor any particular naming convention,
1868 are required in actual use.
1869
1870 For conciseness, declaration coordinates and call coordinates are omitted.
1871
1872 \subsection{Alternative \#1: inline both OUTER and INNER}
1873 \label{app:inlinebothouterandinner}
1874
1875 A suitable abstract instance for an alternative where both
1876 \texttt{OUTER} and \texttt{INNER} are always inlined is shown in 
1877 Figure \refersec{fig:inliningexample1abstractinstance}.
1878
1879 Notice in 
1880 Figure \ref{fig:inliningexample1abstractinstance} 
1881 that the debugging information entry for
1882 \texttt{INNER} (labelled \texttt{INNER.AI.1.1}) is nested in (is a child of)
1883 that for \texttt{OUTER} (labelled \texttt{OUTER.AI.1.1}). Nonetheless, the
1884 abstract instance tree for \texttt{INNER} is considered to be separate
1885 and distinct from that for \texttt{OUTER}.
1886
1887 The call of \texttt{OUTER} shown in 
1888 Figure \refersec{fig:inliningexamplespseudosourcefragment}
1889 might be described as
1890 shown in 
1891 Figure \refersec{fig:inliningexample1concreteinstance}.
1892
1893
1894 \begin{figure}[p]
1895 \begin{dwflisting}
1896 \begin{alltt}
1897     ! Abstract instance for OUTER
1898     ! \addtoindexx{abstract instance!example}
1899 OUTER.AI.1.1:
1900     \DWTAGsubprogram
1901         \DWATname("OUTER")
1902         \DWATinline(\DWINLdeclaredinlined)
1903         ! No low/high PCs
1904 OUTER.AI.1.2:
1905         \DWTAGformalparameter
1906             \DWATname("OUTER\_FORMAL")
1907             \DWATtype(reference to integer)
1908             ! No location
1909 OUTER.AI.1.3:
1910         \DWTAGvariable
1911             \DWATname("OUTER\_LOCAL")
1912             \DWATtype(reference to integer)
1913             ! No location
1914         !
1915         ! Abstract instance for INNER
1916         !
1917 INNER.AI.1.1:
1918         \DWTAGsubprogram
1919             \DWATname("INNER")
1920             \DWATinline(\DWINLdeclaredinlined)
1921             ! No low/high PCs
1922 INNER.AI.1.2:
1923             \DWTAGformalparameter
1924                 \DWATname("INNER\_FORMAL")
1925                 \DWATtype(reference to integer)
1926                 ! No location
1927 INNER.AI.1.3:
1928             \DWTAGvariable
1929                 \DWATname("INNER\_LOCAL")
1930                 \DWATtype(reference to integer)
1931                 ! No location
1932             ...
1933             0
1934         ! No \DWTAGinlinedsubroutine (concrete instance)
1935         ! for INNER corresponding to calls of INNER
1936         ...
1937         0
1938 \end{alltt}
1939 \end{dwflisting}
1940 \caption{Inlining example \#1: abstract instance}
1941 \label{fig:inliningexample1abstractinstance}
1942 \end{figure}
1943
1944 \begin{figure}[p]
1945 \begin{dwflisting}
1946 \begin{alltt}
1947 ! Concrete instance for call "OUTER(7)"
1948 ! \addtoindexx{concrete instance!example}
1949 OUTER.CI.1.1:
1950     \DWTAGinlinedsubroutine
1951         ! No name
1952         \DWATabstractorigin(reference to OUTER.AI.1.1)
1953         \DWATlowpc(...)
1954         \DWAThighpc(...)
1955 OUTER.CI.1.2:
1956         \DWTAGformalparameter
1957             ! No name
1958             \DWATabstractorigin(reference to OUTER.AI.1.2)
1959             \DWATconstvalue(7)
1960 OUTER.CI.1.3:
1961         \DWTAGvariable
1962             ! No name
1963             \DWATabstractorigin(reference to OUTER.AI.1.3)
1964             \DWATlocation(...)
1965         !
1966         ! No \DWTAGsubprogram (abstract instance) for INNER
1967         !
1968         ! Concrete instance for call INNER(OUTER\_LOCAL)
1969         !
1970 INNER.CI.1.1:
1971         \DWTAGinlinedsubroutine
1972             ! No name
1973             \DWATabstractorigin(reference to INNER.AI.1.1)
1974             \DWATlowpc(...)
1975             \DWAThighpc(...)
1976             \DWATstaticlink(...)
1977 INNER.CI.1.2:
1978             \DWTAGformalparameter
1979                 ! No name
1980                 \DWATabstractorigin(reference to INNER.AI.1.2)
1981                 \DWATlocation(...)
1982 INNER.CI.1.3:
1983             \DWTAGvariable
1984                 ! No name
1985                 \DWATabstractorigin(reference to INNER.AI.1.3)
1986                 \DWATlocation(...)
1987             ...
1988             0
1989         ! Another concrete instance of INNER within OUTER
1990         ! for the call "INNER(31)"
1991         ...
1992         0
1993 \end{alltt}
1994 \end{dwflisting}
1995 \caption{Inlining example \#1: concrete instance}
1996 \label{fig:inliningexample1concreteinstance}
1997 \end{figure}
1998
1999 \subsection{Alternative \#2: Inline OUTER, multiple INNERs}
2000 \label{app:inlineoutermultiipleinners}
2001
2002
2003 In the second alternative we assume that subprogram \texttt{INNER}
2004 is not inlinable for some reason, but subprogram \texttt{OUTER} is
2005 inlinable. 
2006 \addtoindexx{concrete instance!example}
2007 Each concrete inlined instance of \texttt{OUTER} has its
2008 own normal instance of \texttt{INNER}. 
2009 The abstract instance for \texttt{OUTER},
2010 \addtoindexx{abstract instance!example}
2011 which includes \texttt{INNER}, is shown in 
2012 Figure \refersec{fig:inliningexample2abstractinstance}.
2013
2014 Note that the debugging information in 
2015 Figure \ref{fig:inliningexample2abstractinstance}
2016 differs from that in 
2017 Figure \refersec{fig:inliningexample1abstractinstance}
2018 in that \texttt{INNER} lacks a 
2019 \DWATinline{} attribute
2020 and therefore is not a distinct abstract instance. \texttt{INNER}
2021 is merely an out\dash of\dash line routine that is part of \texttt{OUTER}\textquoteright s
2022 abstract instance. This is reflected in the Figure by
2023 \addtoindexx{abstract instance!example}
2024 the fact that the labels for \texttt{INNER} use the substring \texttt{OUTER}
2025 instead of \texttt{INNER}.
2026
2027 A resulting 
2028 \addtoindexx{concrete instance!example}
2029 concrete inlined instance of \texttt{OUTER} is shown in
2030 Figure \refersec{fig:inliningexample2concreteinstance}.
2031
2032 Notice in 
2033 Figure \ref{fig:inliningexample2concreteinstance}
2034 that \texttt{OUTER} is expanded as a concrete
2035 \addtoindexx{concrete instance!example}
2036 inlined instance, and that \texttt{INNER} is nested within it as a
2037 concrete out\dash of\dash line subprogram. Because \texttt{INNER} is cloned
2038 for each inline expansion of \texttt{OUTER}, only the invariant
2039 attributes of \texttt{INNER} 
2040 (for example, \DWATname) are specified
2041 in the abstract instance of \texttt{OUTER}, and the low\dash level,
2042 \addtoindexx{abstract instance!example}
2043 instance\dash specific attributes of \texttt{INNER} (for example,
2044 \DWATlowpc) are specified in 
2045 each concrete instance of \texttt{OUTER}.
2046 \addtoindexx{concrete instance!example}
2047
2048 The several calls of \texttt{INNER} within \texttt{OUTER} are compiled as normal
2049 calls to the instance of \texttt{INNER} that is specific to the same
2050 instance of \texttt{OUTER} that contains the calls.
2051
2052 \begin{figure}[t]
2053 \begin{dwflisting}
2054 \begin{alltt}
2055     ! Abstract instance for OUTER
2056     ! \addtoindex{abstract instance}
2057 OUTER.AI.2.1:
2058     \DWTAGsubprogram
2059         \DWATname("OUTER")
2060         \DWATinline(\DWINLdeclaredinlined)
2061         ! No low/high PCs
2062 OUTER.AI.2.2:
2063         \DWTAGformalparameter
2064             \DWATname("OUTER\_FORMAL")
2065             \DWATtype(reference to integer)
2066             ! No location
2067 OUTER.AI.2.3:
2068         \DWTAGvariable
2069             \DWATname("OUTER\_LOCAL")
2070             \DWATtype(reference to integer)
2071             ! No location
2072         !
2073         ! Nested out-of-line INNER subprogram
2074         !
2075 OUTER.AI.2.4:
2076         \DWTAGsubprogram
2077             \DWATname("INNER")
2078             ! No \DWATinline
2079             ! No low/high PCs, frame\_base, etc.
2080 OUTER.AI.2.5:
2081             \DWTAGformalparameter
2082                 \DWATname("INNER\_FORMAL")
2083                 \DWATtype(reference to integer)
2084                 ! No location
2085 OUTER.AI.2.6:
2086             \DWTAGvariable
2087                 \DWATname("INNER\_LOCAL")
2088                 \DWATtype(reference to integer)
2089                 ! No location
2090             ...
2091             0
2092         ...
2093         0
2094 \end{alltt}
2095 \end{dwflisting}
2096 \caption{Inlining example \#2: abstract instance}
2097 \label{fig:inliningexample2abstractinstance}
2098 \end{figure}
2099
2100 \begin{figure}[t]
2101 \begin{dwflisting}
2102 \begin{alltt}
2103
2104     ! Concrete instance for call "OUTER(7)"
2105     !
2106 OUTER.CI.2.1:
2107     \DWTAGinlinedsubroutine
2108         ! No name
2109         \DWATabstractorigin(reference to OUTER.AI.2.1)
2110         \DWATlowpc(...)
2111         \DWAThighpc(...)
2112 OUTER.CI.2.2:
2113         \DWTAGformalparameter
2114             ! No name
2115             \DWATabstractorigin(reference to OUTER.AI.2.2)
2116             \DWATlocation(...)
2117 OUTER.CI.2.3:
2118         \DWTAGvariable
2119             ! No name
2120             \DWATabstractorigin(reference to OUTER.AI.2.3)
2121             \DWATlocation(...)
2122         !
2123         ! Nested out-of-line INNER subprogram
2124         !
2125 OUTER.CI.2.4:
2126         \DWTAGsubprogram
2127             ! No name
2128             \DWATabstractorigin(reference to OUTER.AI.2.4)
2129             \DWATlowpc(...)
2130             \DWAThighpc(...)
2131             \DWATframebase(...)
2132             \DWATstaticlink(...)
2133 OUTER.CI.2.5:
2134             \DWTAGformalparameter
2135                 ! No name
2136                 \DWATabstractorigin(reference to OUTER.AI.2.5)
2137                 \DWATlocation(...)
2138 OUTER.CI.2.6:
2139             \DWTAGvariable
2140                 ! No name
2141                 \DWATabstractorigin(reference to OUTER.AT.2.6)
2142                 \DWATlocation(...)
2143             ...
2144             0
2145         ...
2146         0
2147 \end{alltt}
2148 \end{dwflisting}
2149 \caption{Inlining example \#2: concrete instance}
2150 \label{fig:inliningexample2concreteinstance}
2151 \end{figure}
2152
2153 \subsection{Alternative \#3: inline OUTER, one normal INNER}
2154 \label{app:inlineouteronenormalinner}
2155
2156 In the third approach, one normal subprogram for \texttt{INNER} is
2157 compiled which is called from all concrete inlined instances of
2158 \addtoindexx{concrete instance!example}
2159 \addtoindexx{abstract instance!example}
2160 \texttt{OUTER}. The abstract instance for \texttt{OUTER} is shown in 
2161 Figure \refersec{fig:inliningexample3abstractinstance}.
2162
2163 The most distinctive aspect of that Figure is that subprogram
2164 \texttt{INNER} exists only within the abstract instance of \texttt{OUTER},
2165 and not in \texttt{OUTER}\textquoteright s concrete instance. In the abstract
2166 \addtoindexx{concrete instance!example}
2167 \addtoindexx{abstract instance!example}
2168 instance of \texttt{OUTER}, the description of \texttt{INNER} has the full
2169 complement of attributes that would be expected for a
2170 normal subprogram. 
2171 While attributes such as 
2172 \DWATlowpc,
2173 \DWAThighpc, 
2174 \DWATlocation,
2175 and so on, typically are omitted
2176 \addtoindexx{high PC attribute}
2177 from 
2178 \addtoindexx{low PC attribute}
2179 an 
2180 \addtoindexx{location attribute}
2181 abstract instance because they are not invariant across
2182 instances of the containing abstract instance, in this case
2183 those same attributes are included precisely because they are
2184 invariant -- there is only one subprogram \texttt{INNER} to be described
2185 and every description is the same.
2186
2187 A concrete inlined instance of \texttt{OUTER} is illustrated in
2188 Figure \refersec{fig:inliningexample3concreteinstance}.
2189
2190 Notice in 
2191 Figure \ref{fig:inliningexample3concreteinstance}
2192 that there is no DWARF representation for
2193 \texttt{INNER} at all; the representation of \texttt{INNER} does not vary across
2194 instances of \texttt{OUTER} and the abstract instance of \texttt{OUTER} includes
2195 the complete description of \texttt{INNER}, so that the description of
2196 \texttt{INNER} may be (and for reasons of space efficiency, should be)
2197 omitted from each 
2198 \addtoindexx{concrete instance!example}
2199 concrete instance of \texttt{OUTER}.
2200
2201 There is one aspect of this approach that is problematical from
2202 the DWARF perspective. The single compiled instance of \texttt{INNER}
2203 is assumed to access up\dash level variables of \texttt{OUTER}; however,
2204 those variables may well occur at varying positions within
2205 the frames that contain the 
2206 \addtoindexx{concrete instance!example}
2207 concrete inlined instances. A
2208 compiler might implement this in several ways, including the
2209 use of additional compiler-generated parameters that provide
2210 reference parameters for the up\dash level variables, or a 
2211 compiler-generated static link like parameter that points to the group
2212 of up\dash level entities, among other possibilities. In either of
2213 these cases, the DWARF description for the location attribute
2214 of each uplevel variable needs to be different if accessed
2215 from within \texttt{INNER} compared to when accessed from within the
2216 instances of \texttt{OUTER}. An implementation is likely to require
2217 vendor\dash specific DWARF attributes and/or debugging information
2218 entries to describe such cases.
2219
2220 Note that in C++, a member function of a class defined within
2221 a function definition does not require any vendor\dash specific
2222 extensions because the C++ language disallows access to
2223 entities that would give rise to this problem. (Neither \texttt{extern}
2224 variables nor \texttt{static} members require any form of static link
2225 for accessing purposes.)
2226
2227 \begin{figure}[t]
2228 \begin{dwflisting}
2229 \begin{alltt}
2230     ! Abstract instance for OUTER
2231     ! \addtoindexx{abstract instance!example}
2232 OUTER.AI.3.1:
2233     \DWTAGsubprogram
2234         \DWATname("OUTER")
2235         \DWATinline(\DWINLdeclaredinlined)
2236         ! No low/high PCs
2237 OUTER.AI.3.2:
2238         \DWTAGformalparameter
2239             \DWATname("OUTER\_FORMAL")
2240             \DWATtype(reference to integer)
2241             ! No location
2242 OUTER.AI.3.3:
2243         \DWTAGvariable
2244             \DWATname("OUTER\_LOCAL")
2245             \DWATtype(reference to integer)
2246             ! No location
2247         !
2248         ! Normal INNER
2249         !
2250 OUTER.AI.3.4:
2251         \DWTAGsubprogram
2252             \DWATname("INNER")
2253             \DWATlowpc(...)
2254             \DWAThighpc(...)
2255             \DWATframebase(...)
2256             \DWATstaticlink(...)
2257 OUTER.AI.3.5:
2258             \DWTAGformalparameter
2259                 \DWATname("INNER\_FORMAL")
2260                 \DWATtype(reference to integer)
2261                 \DWATlocation(...)
2262 OUTER.AI.3.6:
2263             \DWTAGvariable
2264                 \DWATname("INNER\_LOCAL")
2265                 \DWATtype(reference to integer)
2266                 \DWATlocation(...)
2267             ...
2268             0
2269         ...
2270         0
2271 \end{alltt}
2272 \end{dwflisting}
2273 \caption{Inlining example \#3: abstract instance}
2274 \label{fig:inliningexample3abstractinstance}
2275 \end{figure}
2276
2277 \begin{figure}[t]
2278 \begin{dwflisting}
2279 \begin{alltt}
2280     ! Concrete instance for call "OUTER(7)"
2281     ! \addtoindexx{concrete instance!example}
2282 OUTER.CI.3.1:
2283     \DWTAGinlinedsubroutine
2284         ! No name
2285         \DWATabstractorigin(reference to OUTER.AI.3.1)
2286         \DWATlowpc(...)
2287         \DWAThighpc(...)
2288         \DWATframebase(...)
2289 OUTER.CI.3.2:
2290         \DWTAGformalparameter
2291             ! No name
2292             \DWATabstractorigin(reference to OUTER.AI.3.2)
2293             ! No type
2294             \DWATlocation(...)
2295 OUTER.CI.3.3:
2296         \DWTAGvariable
2297             ! No name
2298             \DWATabstractorigin(reference to OUTER.AI.3.3)
2299             ! No type
2300             \DWATlocation(...)
2301         ! No \DWTAGsubprogram for "INNER"
2302         ...
2303         0
2304 \end{alltt}
2305 \end{dwflisting}
2306 \caption{Inlining example \#3: concrete instance}
2307 \label{fig:inliningexample3concreteinstance}
2308 \end{figure}
2309
2310 \clearpage
2311 \section{Constant Expression Example}
2312 \label{app:constantexpressionexample}
2313 C++ generalizes the notion of constant expressions to include
2314 constant expression user-defined literals and functions.
2315 The constant declarations in Figure \refersec{fig:constantexpressionscsource}
2316 can be represented as illustrated in 
2317 Figure \refersec{fig:constantexpressionsdwarfdescription}.
2318
2319
2320 \begin{figure}[here]
2321 \begin{lstlisting}[numbers=none]
2322 constexpr double mass = 9.8;
2323 constexpr int square (int x) { return x * x; }
2324 float arr[square(9)]; // square() called and inlined
2325 \end{lstlisting}
2326 \caption{Constant expressions: C++ source} \label{fig:constantexpressionscsource}
2327 \end{figure}
2328
2329
2330 \begin{figure}[!h]
2331 \begin{dwflisting}
2332 \begin{alltt}
2333         ! For variable mass
2334         !
2335 1\$:     \DWTAGconsttype
2336             \DWATtype(reference to "double")
2337 2\$:     \DWTAGvariable
2338             \DWATname("mass")
2339             \DWATtype(reference to 1\$)
2340             \DWATconstexpr(true)
2341             \DWATconstvalue(9.8)
2342         ! Abstract instance for square
2343         !
2344 10\$:    \DWTAGsubprogram
2345             \DWATname("square")
2346             \DWATtype(reference to "int")
2347             \DWATinline(\DWINLinlined)
2348 11\$:        \DWTAGformalparameter
2349                 \DWATname("x")
2350                 \DWATtype(reference to "int")
2351         ! Concrete instance for square(9)
2352         ! \addtoindexx{concrete instance!example}
2353 20\$:    \DWTAGinlinedsubroutine
2354             \DWATabstractorigin(reference to 10\$)
2355             \DWATconstexpr(present)
2356             \DWATconstvalue(81)
2357             \DWTAGformalparameter
2358                 \DWATabstractorigin(reference to 11\$)
2359                 \DWATconstvalue(9)
2360         ! Anonymous array type for arr
2361         !
2362 30\$:    \DWTAGarraytype
2363             \DWATtype(reference to "float")
2364             \DWATbytesize(324) ! 81*4
2365             \DWTAGsubrangetype
2366                 \DWATtype(reference to "int")
2367                 \DWATupperbound(reference to 20\$)
2368         ! Variable arr
2369         !
2370 40\$:    \DWTAGvariable
2371             \DWATname("arr")
2372             \DWATtype(reference to 30\$)
2373 \end{alltt}
2374 \end{dwflisting}
2375 \caption{Constant expressions: DWARF description}
2376 \label{fig:constantexpressionsdwarfdescription}
2377 \end{figure}
2378
2379 \section{Unicode Character Example}
2380 \label{app:unicodecharacterexample}
2381 \addtoindexx{Unicode|see {\textit{also} UTF-8}}
2382 The \addtoindex{Unicode} character encodings in
2383 Figure \refersec{fig:unicodecharacterexamplesource}
2384 can be described in DWARF as illustrated in 
2385 Figure \refersec{fig:unicodecharacterexampledwarfdescription}.
2386
2387 \begin{figure}[!h]
2388 \begin{lstlisting}[numbers=none]
2389 // C++ source
2390 //
2391 char16_t chr_a = u'h';
2392 char32_t chr_b = U'h';
2393 \end{lstlisting}
2394 \caption{Unicode character example: source}
2395 \label{fig:unicodecharacterexamplesource}
2396 \end{figure}
2397
2398 \begin{figure}[h]
2399 \begin{dwflisting}
2400 \begin{alltt}
2401
2402 ! DWARF description
2403 !
2404 1\$: \DWTAGbasetype
2405         \DWATname("char16\_t")
2406         \DWATencoding(\DWATEUTF)
2407         \DWATbytesize(2)
2408 2\$: \DWTAGbasetype
2409         \DWATname("char32\_t")
2410         \DWATencoding(\DWATEUTF)
2411         \DWATbytesize(4)
2412 3\$: \DWTAGvariable
2413         \DWATname("chr\_a")
2414         \DWATtype(reference to 1\$)
2415 4\$: \DWTAGvariable
2416         \DWATname("chr\_b")
2417         \DWATtype(reference to 2\$)
2418 \end{alltt}
2419 \end{dwflisting}
2420 \caption{Unicode character example: DWARF description}
2421 \label{fig:unicodecharacterexampledwarfdescription}
2422 \end{figure}
2423
2424
2425 \section{Type-Safe Enumeration Example}
2426 \label{app:typesafeenumerationexample}
2427
2428 The \addtoindex{C++} type\dash safe enumerations in
2429 \addtoindexx{type-safe enumeration}
2430 Figure \refersec{fig:ctypesafeenumerationexamplesource}
2431 can be described in DWARF as illustrated in 
2432 Figure \refersec{fig:ctypesafeenumerationexampledwarf}.
2433
2434 \clearpage      % Get following source and DWARF on same page
2435
2436 \begin{figure}[H]
2437 \begin{lstlisting}[numbers=none]
2438 // C++ source
2439 //
2440 enum class E { E1, E2=100 };
2441 E e1;
2442 \end{lstlisting}
2443 \caption{Type-safe enumeration example: source}
2444 \label{fig:ctypesafeenumerationexamplesource}
2445 \end{figure}
2446
2447 \begin{figure}[H]
2448 \begin{dwflisting}
2449 \begin{alltt}
2450 ! DWARF description
2451 !
2452 11\$:  \DWTAGenumerationtype
2453           \DWATname("E")
2454           \DWATtype(reference to "int")
2455           \DWATenumclass(present)
2456 12\$:      \DWTAGenumerator
2457               \DWATname("E1")
2458               \DWATconstvalue(0)
2459 13\$:      \DWTAGenumerator
2460               \DWATname("E2")
2461               \DWATconstvalue(100)
2462 14\$:  \DWTAGvariable
2463          \DWATname("e1")
2464          \DWATtype(reference to 11\$)
2465 \end{alltt}
2466 \end{dwflisting}
2467 \caption{Type-safe enumeration example: DWARF description}
2468 \label{fig:ctypesafeenumerationexampledwarf}
2469 \end{figure}
2470
2471
2472 \clearpage
2473 \section{Template Examples}
2474 \label{app:templateexample}
2475
2476 The C++ template example in
2477 Figure \refersec{fig:ctemplateexample1source}
2478 can be described in DWARF as illustrated in 
2479 Figure \refersec{fig:ctemplateexample1dwarf}.
2480
2481 \begin{figure}[h]
2482 \begin{lstlisting}
2483 // C++ source
2484 //
2485 template<class T>
2486 struct wrapper {
2487     T comp;
2488 };
2489 wrapper<int> obj;
2490 \end{lstlisting}
2491 \caption{C++ template example \#1: source}
2492 \label{fig:ctemplateexample1source}
2493 \end{figure}
2494
2495 \begin{figure}[h]
2496 \begin{dwflisting}
2497 \begin{alltt}
2498 ! DWARF description
2499 !
2500 11\$: \DWTAGstructuretype
2501         \DWATname("wrapper")
2502 12\$:    \DWTAGtemplatetypeparameter
2503             \DWATname("T")
2504             \DWATtype(reference to "int")
2505 13\$:    \DWTAGmember
2506             \DWATname("comp")
2507             \DWATtype(reference to 12\$)
2508 14\$: \DWTAGvariable
2509         \DWATname("obj")
2510         \DWATtype(reference to 11\$)
2511 \end{alltt}
2512 \end{dwflisting}
2513 \caption{C++ template example \#1: DWARF description}
2514 \label{fig:ctemplateexample1dwarf}
2515 \end{figure}
2516
2517 The actual type of the component \texttt{comp} is \texttt{int}, but in the DWARF
2518 the type references the
2519 \DWTAGtemplatetypeparameter{}
2520 for \texttt{T}, which in turn references \texttt{int}. This implies that in the
2521 original template comp was of type \texttt{T} and that was replaced
2522 with \texttt{int} in the instance. 
2523
2524 \needlines{10}
2525 There exist situations where it is
2526 not possible for the DWARF to imply anything about the nature
2527 of the original template. 
2528 Consider the C++ template source in
2529 Figure \refersec{fig:ctemplateexample2source}
2530 and the DWARF that can describe it in
2531 Figure \refersec{fig:ctemplateexample2dwarf}.
2532
2533 \begin{figure}[!h]
2534 \begin{lstlisting}
2535 // C++ source
2536 //
2537     template<class T>
2538     struct wrapper {
2539         T comp;
2540     };
2541     template<class U>
2542     void consume(wrapper<U> formal)
2543     {
2544         ...
2545     }
2546     wrapper<int> obj;
2547     consume(obj);
2548 \end{lstlisting}
2549 \caption{C++ template example \#2: source}
2550 \label{fig:ctemplateexample2source}
2551 \end{figure}
2552
2553 \begin{figure}[h]
2554 \begin{dwflisting}
2555 \begin{alltt}
2556 ! DWARF description
2557 !
2558 11\$:  \DWTAGstructuretype
2559           \DWATname("wrapper")
2560 12\$:      \DWTAGtemplatetypeparameter
2561               \DWATname("T")
2562               \DWATtype(reference to "int")
2563 13\$:      \DWTAGmember
2564               \DWATname("comp")
2565               \DWATtype(reference to 12\$)
2566 14\$:  \DWTAGvariable
2567           \DWATname("obj")
2568           \DWATtype(reference to 11\$)
2569 21\$:  \DWTAGsubprogram
2570           \DWATname("consume")
2571 22\$:      \DWTAGtemplatetypeparameter
2572               \DWATname("U")
2573               \DWATtype(reference to "int")
2574 23\$:      \DWTAGformalparameter
2575               \DWATname("formal")
2576               \DWATtype(reference to 11\$)
2577 \end{alltt}
2578 \end{dwflisting}
2579 \caption{C++ template example \#2: DWARF description}
2580 \label{fig:ctemplateexample2dwarf}
2581 \end{figure}
2582
2583 In the \DWTAGsubprogram{} 
2584 entry for the instance of consume, \texttt{U} is described as \texttt{int}. 
2585 The type of formal is \texttt{wrapper\textless U\textgreater} in
2586 the source. DWARF only represents instantiations of templates;
2587 there is no entry which represents \texttt{wrapper\textless U\textgreater} 
2588 which is neither
2589 a template parameter nor a template instantiation. The type
2590 of formal is described as \texttt{wrapper\textless int\textgreater},
2591 the instantiation of \texttt{wrapper\textless U\textgreater},
2592 in the \DWATtype{} attribute at 
2593 23\$. 
2594 There is no
2595 description of the relationship between template type parameter
2596 \texttt{T} at 12\$ and \texttt{U} at 22\$ which was used to instantiate
2597 \texttt{wrapper\textless U\textgreater}.
2598
2599 A consequence of this is that the DWARF information would
2600 not distinguish between the existing example and one where
2601 the formal parameter of \texttt{consume} were declared in the source to be
2602 \texttt{wrapper\textless int\textgreater}.
2603
2604
2605 \section{Template Alias Examples}
2606 \label{app:templatealiasexample}
2607
2608 The \addtoindex{C++} template alias shown in
2609 Figure \refersec{fig:ctemplatealiasexample1source}
2610 can be described in DWARF as illustrated 
2611 \addtoindexx{template alias example} in 
2612 Figure \refersec{fig:ctemplatealiasexample1dwarf}.
2613
2614 \begin{figure}[h]
2615 \begin{lstlisting}
2616 // C++ source, template alias example 1
2617 //
2618 template<typename T, typename U>
2619 struct Alpha {
2620     T tango;
2621     U uniform;
2622 };
2623 template<typename V> using Beta = Alpha<V,V>;
2624 Beta<long> b;
2625 \end{lstlisting}
2626 \caption{C++ template alias example \#1: source}
2627 \label{fig:ctemplatealiasexample1source}
2628 \end{figure}
2629
2630 \begin{figure}[h]
2631 \addtoindexx{template alias example 1}
2632 \begin{dwflisting}
2633 \begin{alltt}
2634 ! DWARF representation for variable 'b'
2635 !
2636 20\$:  \DWTAGstructuretype
2637           \DWATname("Alpha")
2638 21\$:      \DWTAGtemplatetypeparameter
2639               \DWATname("T")
2640               \DWATtype(reference to "long")
2641 22\$:      \DWTAGtemplatetypeparameter
2642               \DWATname("U")
2643               \DWATtype(reference to "long")
2644 23\$:      \DWTAGmember
2645               \DWATname("tango")
2646               \DWATtype(reference to 21\$)
2647 24\$:      \DWTAGmember
2648               \DWATname("uniform")
2649               \DWATtype(reference to 22\$)
2650 25\$:  \DWTAGtemplatealias
2651           \DWATname("Beta")
2652           \DWATtype(reference to 20\$)
2653 26\$:      \DWTAGtemplatetypeparameter
2654               \DWATname("V")
2655               \DWATtype(reference to "long")
2656 27\$:  \DWTAGvariable
2657           \DWATname("b")
2658           \DWATtype(reference to 25\$)
2659 \end{alltt}
2660 \end{dwflisting}
2661 \caption{C++ template alias example \#1: DWARF description}
2662 \label{fig:ctemplatealiasexample1dwarf}
2663 \end{figure}
2664
2665 Similarly, the \addtoindex{C++} template alias shown in
2666 Figure \refersec{fig:ctemplatealiasexample2source}
2667 can be described in DWARF as illustrated 
2668 \addtoindexx{template alias example} in 
2669 Figure \refersec{fig:ctemplatealiasexample2dwarf}.
2670
2671 \begin{figure}[h]
2672 \begin{lstlisting}
2673 // C++ source, template alias example 2
2674 //
2675 template<class TX> struct X { };
2676 template<class TY> struct Y { };
2677 template<class T> using Z = Y<T>;
2678 X<Y<int>> y;
2679 X<Z<int>> z;
2680 \end{lstlisting}
2681 \caption{C++ template alias example \#2: source}
2682 \label{fig:ctemplatealiasexample2source}
2683 \end{figure}
2684
2685 \begin{figure}[h]
2686 \addtoindexx{template alias example 2}
2687 \begin{dwflisting}
2688 \begin{alltt}
2689 ! DWARF representation for X<Y<int>>
2690 !
2691 30\$:  \DWTAGstructuretype
2692           \DWATname("Y")
2693 31\$:      \DWTAGtemplatetypeparameter
2694               \DWATname("TY")
2695               \DWATtype(reference to "int")
2696 32\$:  \DWTAGstructuretype
2697           \DWATname("X")
2698 33\$:      \DWTAGtemplatetypeparameter
2699               \DWATname("TX")
2700               \DWATtype(reference to 30\$)
2701 !
2702 ! DWARF representation for X<Z<int>>
2703 !
2704 40\$:  \DWTAGtemplatealias
2705           \DWATname("Z")
2706           \DWATtype(reference to 30\$)
2707 41\$:      \DWTAGtemplatetypeparameter
2708               \DWATname("T")
2709               \DWATtype(reference to "int")
2710 42\$:  \DWTAGstructuretype
2711           \DWATname("X")
2712 43\$:      \DWTAGtemplatetypeparameter
2713               \DWATname("TX")
2714               \DWATtype(reference to 40\$)
2715 !
2716 ! Note that 32\$ and 42\$ are actually the same type
2717 !
2718 50\$:  \DWTAGvariable
2719           \DWATname("y")
2720           \DWATtype(reference to \$32)
2721 51\$:  \DWTAGvariable
2722           \DWATname("z")
2723           \DWATtype(reference to \$42)
2724 \end{alltt}
2725 \end{dwflisting}
2726 \caption{C++ template alias example \#2: DWARF description}
2727 \label{fig:ctemplatealiasexample2dwarf}
2728 \end{figure}
2729
2730 \clearpage
2731 \section{Implicit Pointer Examples}
2732 \label{app:implicitpointerexamples}
2733 If the compiler determines that the value of an object is
2734 constant (either throughout the program, or within a specific
2735 range), it may choose to materialize that constant only when
2736 used, rather than store it in memory or in a register. The
2737 \DWOPimplicitvalue{} operation can be used to describe such a
2738 value. Sometimes, the value may not be constant, but still can be
2739 easily rematerialized when needed. A DWARF expression terminating
2740 in \DWOPstackvalue{} can be used for this case. The compiler may
2741 also eliminate a pointer value where the target of the pointer
2742 resides in memory, and the \DWOPstackvalue{} operator may be used
2743 to rematerialize that pointer value. In other cases, the compiler
2744 will eliminate a pointer to an object that itself needs to be
2745 materialized. Since the location of such an object cannot be
2746 represented as a memory address, a DWARF expression cannot give
2747 either the location or the actual value or a pointer variable
2748 that would refer to that object. The \DWOPimplicitpointer{}
2749 operation can be used to describe the pointer, and the debugging
2750 information entry to which its first operand refers describes the
2751 value of the dereferenced object. A DWARF consumer will not be
2752 able to show the location or the value of the pointer variable,
2753 but it will be able to show the value of the dereferenced
2754 pointer.
2755
2756 Consider the \addtoindex{C} source shown in 
2757 Figure \refersec{fig:cimplicitpointerexample1source}.
2758 Assume that the function \texttt{foo} is not inlined,
2759 that the argument x is passed in register 5, and that the
2760 function \texttt{foo} is optimized by the compiler into just 
2761 an increment of the volatile variable \texttt{v}. Given these
2762 assumptions a possible DWARF description is shown in
2763 Figure \refersec{fig:cimplicitpointerexample1dwarf}.
2764
2765 \begin{figure}[h]
2766 \begin{lstlisting}
2767 struct S { short a; char b, c; };
2768 volatile int v;
2769 void foo (int x)
2770 {
2771     struct S s = { x, x + 2, x + 3 };
2772     char *p = &s.b;
2773     s.a++;
2774     v++;
2775 }
2776 int main ()
2777 {
2778     foo (v+1);
2779     return 0;
2780 }
2781 \end{lstlisting}
2782 \caption{C implicit pointer example \#1: source}
2783 \label{fig:cimplicitpointerexample1source}
2784 \end{figure}
2785
2786 \begin{figure}[h]
2787 \addtoindexx{implicit pointer example \#1}
2788 \begin{dwflisting}
2789 \begin{alltt}
2790 1\$: \DWTAGstructuretype
2791         \DWATname("S")
2792         \DWATbytesize(4)
2793 10\$:    \DWTAGmember
2794             \DWATname("a")
2795             \DWATtype(reference to "short int")
2796             \DWATdatamemberlocation(constant 0)
2797 11\$:    \DWTAGmember
2798             \DWATname("b")
2799             \DWATtype(reference to "char")
2800             \DWATdatamemberlocation(constant 2)
2801 12\$:    \DWTAGmember
2802             \DWATname("c")
2803             \DWATtype(reference to "char")
2804             \DWATdatamemberlocation(constant 3)
2805 2\$: \DWTAGsubprogram
2806         \DWATname("foo")
2807 20\$:    \DWTAGformalparameter
2808             \DWATname("x")
2809             \DWATtype(reference to "int")
2810             \DWATlocation(\DWOPregfive)
2811 21\$:    \DWTAGvariable
2812             \DWATname("s")
2813             \DWATlocation(expression=
2814                 \DWOPbregfive(1) \DWOPstackvalue \DWOPpiece(2)
2815                 \DWOPbregfive(2) \DWOPstackvalue \DWOPpiece(1)
2816                 \DWOPbregfive(3) \DWOPstackvalue \DWOPpiece(1))
2817 22\$:    \DWTAGvariable
2818             \DWATname("p")
2819             \DWATtype(reference to "char *")
2820             \DWATlocation(expression=
2821             \DWOPimplicitpointer(reference to 21\$, 2))
2822 \end{alltt}
2823 \end{dwflisting}
2824 \caption{C implicit pointer example \#1: DWARF description}
2825 \label{fig:cimplicitpointerexample1dwarf}
2826 \end{figure}
2827
2828 In Figure \refersec{fig:cimplicitpointerexample1dwarf},
2829 even though variables \texttt{s} and \texttt{p} are both optimized 
2830 away completely, this DWARF description still allows a debugger to 
2831 print the value of the variable \texttt{s}, namely \texttt{(2, 3, 4)}. 
2832 Similarly, because the variable \texttt{s} does not live in
2833 memory, there is nothing to print for the value of \texttt{p}, but the 
2834 debugger should still be able to show that \texttt{p[0]} is 3, 
2835 \texttt{p[1]} is 4, \texttt{p[-1]} is 0 and \texttt{p[-2]} is 2.
2836
2837 \needlines{6}
2838 As a further example, consider the C source 
2839 shown in Figure \refersec{fig:cimplicitpointerexample2source}. Make
2840 the following assumptions about how the code is compiled:
2841 \begin{itemize}
2842 \item The function \texttt{foo} is inlined
2843 into function \texttt{main}
2844 \item The body of the main function is optimized to just
2845 three blocks of instructions which each increment the volatile
2846 variable \texttt{v}, followed by a block of instructions to return 0 from
2847 the function
2848 \item Label \texttt{label0} is at the start of the main
2849 function, \texttt{label1} follows the first \texttt{v++} block, 
2850 \texttt{label2} follows the second \texttt{v++} block and 
2851 \texttt{label3} is at the end of the main function
2852 \item Variable \texttt{b} is optimized away completely, as it isn't used
2853 \item The string literal \texttt{"opq"} is optimized away as well
2854 \end{itemize}
2855 Given these assumptions a possible DWARF description is shown in
2856 Figure \refersec{fig:cimplicitpointerexample2dwarf}.
2857
2858 \begin{figure}[h]
2859 \begin{lstlisting}
2860 static const char *b = "opq";
2861 volatile int v;
2862 static inline void foo (int *p)
2863 {
2864     (*p)++;
2865     v++;
2866     p++;
2867     (*p)++;
2868     v++;
2869 }
2870 int main ()
2871 {
2872     int a[2] = { 1, 2 };
2873     v++;
2874     foo (a);
2875     return a[0] + a[1] - 5;
2876 }
2877 \end{lstlisting}
2878 \caption{C implicit pointer example \#2: source}
2879 \label{fig:cimplicitpointerexample2source}
2880 \end{figure}
2881
2882 \begin{figure}[h]
2883 \addtoindexx{implicit pointer example \#2}
2884 \begin{dwflisting}
2885 \begin{alltt}
2886 1\$: \DWTAGvariable
2887         \DWATname("b")
2888         \DWATtype(reference to "const char *")
2889         \DWATlocation(expression=
2890             \DWOPimplicitpointer(reference to 2$, 0))
2891 2\$: \DWTAGdwarfprocedure
2892         \DWATlocation(expression=
2893             \DWOPimplicitvalue(4, \{'o', 'p', 'q', '\slash0'\}))
2894 3\$: \DWTAGsubprogram
2895         \DWATname("foo")
2896         \DWATinline(\DWINLdeclaredinlined)
2897 30\$:    \DWTAGformalparameter
2898             \DWATname("p")
2899             \DWATtype(reference to "int *")
2900 4\$: \DWTAGsubprogram
2901         \DWATname("main")
2902 40\$:   \DWTAGvariable
2903             \DWATname("a")
2904             \DWATtype(reference to "int[2]")
2905             \DWATlocation(location list 98$)
2906 41\$:    \DWTAGinlinedsubroutine
2907             \DWATabstractorigin(reference to 3$)
2908 42\$:        \DWTAGformalparameter
2909             \DWATabstractorigin(reference to 30$)
2910             \DWATlocation(location list 99$)
2911
2912 ! .debug_loc section
2913 98\$:<label0 in main> .. <label1 in main>
2914         \DWOPlitone \DWOPstackvalue \DWOPpiece(4)
2915         \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
2916     <label1 in main> .. <label2 in main>
2917         \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
2918         \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
2919     <label2 in main> .. <label3 in main>
2920         \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
2921         \DWOPlitthree \DWOPstackvalue \DWOPpiece(4)
2922     0 .. 0
2923 99\$:<label1 in main> .. <label2 in main>
2924         \DWOPimplicitpointer(reference to 40\$, 0)
2925     <label2 in main> .. <label3 in main>
2926         \DWOPimplicitpointer(reference to 40\$, 4)
2927     0 .. 0
2928 \end{alltt}
2929 \end{dwflisting}
2930 \caption{C implicit pointer example \#2: DWARF description}
2931 \label{fig:cimplicitpointerexample2dwarf}
2932 \end{figure}