300a99f3a29feee8ce679528491d1c63a0ece6f8
[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 \vspace{3mm}
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 \referfol{fig:FortranmultidimensionalcoarrayDWARFdescription}.
634
635 \begin{figure}[here]
636 \begin{lstlisting}
637         INTEGER X(10,11,12)[2,3,*]
638 \end{lstlisting}
639 \caption{Fortran multidimensional 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 \clearpage
836 \subsection{Fortran Dynamic Type Example}
837 \label{app:fortrandynamictypeexample}
838 Consider the \addtoindex{Fortran 90} example of dynamic properties in 
839 Figure \refersec{fig:fortrandynamictypeexamplesource}.
840 This can be represented in DWARF as illustrated in 
841 Figure \refersec{fig:fortrandynamictypeexampledwarfdescription}.
842 Note that unnamed dynamic types are used to avoid replicating
843 the full description of the underlying type \texttt{dt} that is shared by
844 several variables.
845
846 \begin{figure}[h]
847 \begin{lstlisting}
848             program sample
849      
850         type :: dt (l)
851             integer, len :: l
852             integer :: arr(l)
853         end type
854
855         integer :: n = 4
856         contains
857
858         subroutine s()
859             type (dt(n))               :: t1
860             type (dt(n)), pointer      :: t2
861             type (dt(n)), allocatable  :: t3, t4
862         end subroutine
863      
864         end sample
865 \end{lstlisting}
866 \caption{Fortran dynamic type example: source}
867 \label{fig:fortrandynamictypeexamplesource}
868 \end{figure}
869
870 \begin{figure}[h]
871 \begin{dwflisting}
872 \begin{alltt}
873 11$:    \DWTAGstructuretype
874             \DWATname("dt")
875             \DWTAGmember
876                 ...
877                         ...
878
879 13$:    \DWTAGdynamictype             ! plain version
880             \DWATdatalocation (dwarf expression to locate raw data)
881             \DWATtype (11$)
882
883 14$:    \DWTAGdynamictype             ! 'pointer' version
884             \DWATdatalocation (dwarf expression to locate raw data)
885             \DWATassociated (dwarf expression to test if associated)
886             \DWATtype (11$)
887
888 15$:    \DWTAGdynamictype             ! 'allocatable' version
889             \DWATdatalocation (dwarf expression to locate raw data)
890             \DWATallocated (dwarf expression to test is allocated)
891             \DWATtype (11$)
892
893 16$:    \DWTAGvariable
894             \DWATname ("t1")
895             \DWATtype (13$)
896             \DWATlocation (dwarf expression to locate descriptor)
897 17$:    \DWTAGvariable
898             \DWATname ("t2")
899             \DWATtype (14$)
900             \DWATlocation (dwarf expression to locate descriptor)
901 18$:    \DWTAGvariable
902             \DWATname ("t3")
903             \DWATtype (15$)
904             \DWATlocation (dwarf expression to locate descriptor)
905 19$:    \DWTAGvariable
906             \DWATname ("t4")
907             \DWATtype (15$)
908             \DWATlocation (dwarf expression to locate descriptor)
909 \end{alltt}
910 \end{dwflisting}
911 \caption{Fortran dynamic type example: DWARF description}
912 \label{fig:fortrandynamictypeexampledwarfdescription}
913 \end{figure}
914
915
916 \clearpage
917 \subsection{Ada Example}
918 \label{app:adaexample}
919 Figure \refersec{fig:adaexamplesourcefragment}
920 illustrates two kinds of \addtoindex{Ada} 
921 parameterized array, one embedded in a record.
922
923 \begin{figure}[here]
924 \begin{lstlisting}
925 M : INTEGER := <exp>;
926 VEC1 : array (1..M) of INTEGER;
927 subtype TEENY is INTEGER range 1..100;
928 type ARR is array (INTEGER range <>) of INTEGER;
929 type REC2(N : TEENY := 100) is record
930     VEC2 : ARR(1..N);
931 end record;
932
933 OBJ2B : REC2;
934 \end{lstlisting}
935 \caption{Ada example: source fragment}
936 \label{fig:adaexamplesourcefragment}
937 \end{figure}
938
939 \texttt{VEC1} illustrates an (unnamed) array type where the upper bound
940 of the first and only dimension is determined at runtime. 
941 \addtoindex{Ada}
942 semantics require that the value of an array bound is fixed at
943 the time the array type is elaborated (where \textit{elaboration} refers
944 to the runtime executable aspects of type processing). For
945 the purposes of this example, we assume that there are no
946 other assignments to \texttt{M} so that it safe for the \texttt{REC1} type
947 description to refer directly to that variable (rather than
948 a compiler-generated copy).
949
950 \texttt{REC2} illustrates another array type (the unnamed type of
951 component \texttt{VEC2}) where the upper bound of the first and only
952 bound is also determined at runtime. In this case, the upper
953 bound is contained in a discriminant of the containing record
954 type. (A \textit{discriminant} is a component of a record whose value
955 cannot be changed independently of the rest of the record
956 because that value is potentially used in the specification
957 of other components of the record.)
958
959 The DWARF description is shown in 
960 Figure \refersec{fig:adaexampledwarfdescription}.
961
962
963 Interesting aspects about this example are:
964 \begin{enumerate}[1. ]
965 \item The array \texttt{VEC2} is \doublequote{immediately} contained within structure
966 \texttt{REC2} (there is no intermediate descriptor or indirection),
967 which is reflected in the absence of a \DWATdatalocation{}
968 attribute on the array type at 28\$.
969
970 \item One of the bounds of \texttt{VEC2} is nonetheless dynamic and part of
971 the same containing record. It is described as a reference to
972 a member, and the location of the upper bound is determined
973 as for any member. That is, the location is determined using
974 an address calculation relative to the base of the containing
975 object.  
976
977 A consumer must notice that the referenced bound is a
978 member of the same containing object and implicitly push the
979 base address of the containing object just as for accessing
980 a data member generally.
981
982 \item The lack of a subtype concept in DWARF means that DWARF types
983 serve the role of subtypes and must replicate information from
984 what should be the parent type. For this reason, DWARF for
985 the unconstrained array type \texttt{ARR} is not needed for the purposes
986 of this example and therefore is not shown.
987 \end{enumerate}
988
989 \begin{figure}[p]
990 \begin{dwflisting}
991 \begin{alltt}
992 11\$: \DWTAGvariable
993         \DWATname("M")
994         \DWATtype(reference to INTEGER)
995 12\$: \DWTAGarraytype
996         ! No name, default (\addtoindex{Ada}) order, default stride
997         \DWATtype(reference to INTEGER)
998 13\$:    \DWTAGsubrangetype
999             \DWATtype(reference to INTEGER)
1000             \DWATlowerbound(constant 1)
1001             \DWATupperbound(reference to variable M at 11\$)
1002 14\$: \DWTAGvariable
1003         \DWATname("VEC1")
1004         \DWATtype(reference to array type at 12\$)
1005      . . .
1006 21\$: \DWTAGsubrangetype
1007         \DWATname("TEENY")
1008         \DWATtype(reference to INTEGER)
1009         \DWATlowerbound(constant 1)
1010         \DWATupperbound(constant 100)
1011      . . .
1012 26\$: \DWTAGstructuretype
1013         \DWATname("REC2")
1014 27\$:    \DWTAGmember
1015             \DWATname("N")
1016             \DWATtype(reference to subtype TEENY at 21\$)
1017             \DWATdatamemberlocation(constant 0)
1018 28\$:    \DWTAGarraytype
1019             ! No name, default (\addtoindex{Ada}) order, default stride
1020             ! Default data location
1021             \DWATtype(reference to INTEGER)
1022 29\$:        \DWTAGsubrangetype
1023                 \DWATtype(reference to subrange TEENY at 21\$)
1024                 \DWATlowerbound(constant 1)
1025                 \DWATupperbound(reference to member N at 27\$)
1026 30\$:    \DWTAGmember
1027             \DWATname("VEC2")
1028             \DWATtype(reference to array "subtype" at 28\$)
1029             \DWATdatamemberlocation(machine=
1030                 \DWOPlitn                  ! where n == offset(REC2, VEC2)
1031                 \DWOPplus)
1032      . . .
1033 41\$: \DWTAGvariable
1034         \DWATname("OBJ2B")
1035         \DWATtype(reference to REC2 at 26\$)
1036         \DWATlocation(...as appropriate...)
1037 \end{alltt}
1038 \end{dwflisting}
1039 \caption{Ada example: DWARF description}
1040 \label{fig:adaexampledwarfdescription}
1041 \end{figure}
1042
1043 \clearpage
1044
1045 \subsection{Pascal Example}
1046 \label{app:pascalexample}
1047 The Pascal \addtoindexx{Pascal example} source in 
1048 Figure \referfol{fig:packedrecordexamplesourcefragment}
1049 is used to illustrate the representation of packed unaligned
1050 \addtoindex{bit fields}.
1051
1052 \begin{figure}[here]
1053 \begin{lstlisting}
1054 TYPE T : PACKED RECORD                  ! bit size is 2
1055          F5 : BOOLEAN;                  ! bit offset is 0
1056          F6 : BOOLEAN;                  ! bit offset is 1
1057          END;
1058 VAR V :  PACKED RECORD
1059          F1 : BOOLEAN;                  ! bit offset is 0
1060          F2 : PACKED RECORD             ! bit offset is 1
1061               F3 : INTEGER;             ! bit offset is 0 in F2, 1 in V
1062               END;
1063          F4 : PACKED ARRAY [0..1] OF T; ! bit offset is 33
1064          F7 : T;                        ! bit offset is 37
1065          END;
1066 \end{lstlisting}
1067 \caption{Packed record example: source fragment}
1068 \label{fig:packedrecordexamplesourcefragment}
1069 \end{figure}
1070
1071 The DWARF representation in 
1072 Figure \refersec{fig:packedrecordexampledwarfdescription} 
1073 is appropriate. 
1074 \DWTAGpackedtype{} entries could be added to
1075 better represent the source, but these do not otherwise affect
1076 the example and are omitted for clarity. Note that this same
1077 representation applies to both typical big\dash \ and 
1078 little\dash endian
1079 architectures using the conventions described in 
1080 Section \refersec{chap:datamemberentries}.
1081
1082 \begin{figure}[h]
1083 \figurepart{1}{2}
1084 \begin{dwflisting}
1085 \begin{alltt}
1086 10\$: \DWTAGbasetype
1087         \DWATname("BOOLEAN")
1088             ...
1089 11\$: \DWTAGbasetype
1090         \DWATname("INTEGER")
1091             ...
1092 20\$: \DWTAGstructuretype
1093         \DWATname("T")
1094         \DWATbitsize(2)
1095         \DWTAGmember
1096             \DWATname("F5")
1097             \DWATtype(reference to 10$)
1098             \DWATdatabitoffset(0)        ! may be omitted
1099             \DWATbitsize(1)
1100 \end{alltt}
1101 \end{dwflisting}
1102 \caption{Packed record example: DWARF description}
1103 \label{fig:packedrecordexampledwarfdescription}
1104 \end{figure}
1105
1106 \begin{figure}[h]
1107 \figurepart{2}{2}
1108 \begin{dwflisting}
1109 \begin{alltt}
1110         \DWTAGmember
1111             \DWATname("F6")
1112             \DWATtype(reference to 10$)
1113             \DWATdatabitoffset(1)
1114             \DWATbitsize(1)
1115 21\$: \DWTAGstructuretype                  ! anonymous type for F2
1116         \DWTAGmember
1117             \DWATname("F3")
1118             \DWATtype(reference to 11\$)
1119 22\$: \DWTAGarraytype                      ! anonymous type for F4
1120         \DWATtype(reference to 20\$)
1121         \DWTAGsubrangetype
1122             \DWATtype(reference to 11\$)
1123             \DWATlowerbound(0)
1124             \DWATupperbound(1)
1125         \DWATbitstride(2)
1126         \DWATbitsize(4) \addtoindexx{bit size attribute}
1127 23\$: \DWTAGstructuretype                  ! anonymous type for V
1128         \DWATbitsize(39) \addtoindexx{bit size attribute}
1129         \DWTAGmember
1130             \DWATname("F1")
1131             \DWATtype(reference to 10\$)
1132             \DWATdatabitoffset(0)        ! may be omitted
1133             \DWATbitsize(1) ! may be omitted
1134         \DWTAGmember
1135             \DWATname("F2")
1136             \DWATtype(reference to 21\$)
1137             \DWATdatabitoffset(1)
1138             \DWATbitsize(32) ! may be omitted
1139         \DWTAGmember
1140             \DWATname("F4")
1141             \DWATtype(reference to 22\$)
1142             \DWATdatabitoffset(33)
1143             \DWATbitsize(4) ! may be omitted
1144         \DWTAGmember
1145             \DWATname("F7")
1146             \DWATtype(reference to 20\$)    ! type T
1147             \DWATdatabitoffset(37)
1148             \DWATbitsize(2) \addtoindexx{bit size attribute}              ! may be omitted
1149      \DWTAGvariable
1150         \DWATname("V")
1151         \DWATtype(reference to 23\$)
1152         \DWATlocation(...)
1153         ...
1154 \end{alltt}
1155 \end{dwflisting}
1156 \begin{center}
1157 \vspace{3mm}
1158 Figure~\ref{fig:packedrecordexampledwarfdescription}: Packed record example: DWARF description \textit{(concluded)}
1159 \end{center}
1160 \end{figure}
1161
1162 \clearpage
1163 \section{Namespace Example}
1164 \label{app:namespaceexample}
1165
1166 The \addtoindex{C++} example in 
1167 Figure \refersec{fig:namespaceexamplesourcefragment}
1168 is used 
1169 \addtoindexx{namespace (C++)!example}
1170 to illustrate the representation of namespaces.
1171 The DWARF representation in 
1172 Figure \refersec{fig:namespaceexampledwarfdescription}
1173 is appropriate.
1174
1175 \begin{figure}[h]
1176 \begin{lstlisting}
1177 namespace {
1178     int i;
1179 }
1180 namespace A {
1181     namespace B {
1182         int j;
1183         int   myfunc (int a);
1184         float myfunc (float f) { return f - 2.0; }
1185         int   myfunc2(int a)   { return a + 2; }
1186     }
1187 }
1188 namespace Y {
1189     using A::B::j;         // (1) using declaration
1190     int foo;
1191 }
1192 using A::B::j;             // (2) using declaration
1193 namespace Foo = A::B;      // (3) namespace alias
1194 using Foo::myfunc;         // (4) using declaration
1195 using namespace Foo;       // (5) using directive
1196 namespace A {
1197     namespace B {
1198         using namespace Y; // (6) using directive
1199         int k;
1200     }
1201 }
1202 int Foo::myfunc(int a)
1203 {
1204     i = 3;
1205     j = 4;
1206     return myfunc2(3) + j + i + a + 2;
1207 }
1208 \end{lstlisting}
1209 \caption{Namespace example: source fragment}
1210 \label{fig:namespaceexamplesourcefragment}
1211 \end{figure}
1212
1213
1214 \begin{figure}[p]
1215 \figurepart{1}{2}
1216 \begin{dwflisting}
1217 \begin{alltt}
1218
1219 1\$:  \DWTAGbasetype
1220         \DWATname("int")
1221         ...
1222 2\$:  \DWTAGbasetype
1223         \DWATname("float")
1224         ...
1225 6\$:  \DWTAGnamespace
1226         ! no \DWATname attribute
1227 7\$:
1228         \DWTAGvariable
1229             \DWATname("i")
1230             \DWATtype(reference to 1\$)
1231             \DWATlocation ...
1232             ...
1233 10\$: \DWTAGnamespace
1234         \DWATname("A")
1235 20\$:    \DWTAGnamespace
1236             \DWATname("B")
1237 30\$:        \DWTAGvariable
1238                 \DWATname("j")
1239                 \DWATtype(reference to 1\$)
1240                 \DWATlocation ...
1241                 ...
1242 34\$:        \DWTAGsubprogram
1243                 \DWATname("myfunc")
1244                 \DWATtype(reference to 1\$)
1245                 ...
1246 36\$:        \DWTAGsubprogram
1247                 \DWATname("myfunc")
1248                 \DWATtype(reference to 2\$)
1249                 ...
1250 38\$:        \DWTAGsubprogram
1251                 \DWATname("myfunc2")
1252                 \DWATlowpc ...
1253                 \DWAThighpc ...
1254                 \DWATtype(reference to 1\$)
1255                 ...
1256 \end{alltt}
1257 \end{dwflisting}
1258 \caption{Namespace example: DWARF description}
1259 \label{fig:namespaceexampledwarfdescription}
1260 \end{figure}
1261
1262 \begin{figure}
1263 \figurepart{2}{2}
1264 \begin{dwflisting}
1265 \begin{alltt}
1266 40\$: \DWTAGnamespace
1267         \DWATname("Y")
1268         \DWTAGimporteddeclaration            ! (1) using-declaration
1269             \DWATimport(reference to 30\$)
1270         \DWTAGvariable
1271             \DWATname("foo")
1272             \DWATtype(reference to 1\$)
1273             \DWATlocation ...
1274             ...
1275      \DWTAGimporteddeclaration               ! (2) using declaration
1276         \DWATimport(reference to 30\$)
1277         \DWTAGimporteddeclaration            ! (3) namespace alias
1278             \DWATname("Foo")
1279             \DWATimport(reference to 20\$)
1280         \DWTAGimporteddeclaration            ! (4) using declaration
1281             \DWATimport(reference to 34\$)     !     - part 1
1282         \DWTAGimporteddeclaration            ! (4) using declaration
1283             \DWATimport(reference to 36\$)     !     - part 2
1284         \DWTAGimportedmodule                 ! (5) using directive
1285             \DWATimport(reference to 20\$)
1286         \DWTAGnamespace
1287             \DWATextension(reference to 10\$)
1288             \DWTAGnamespace
1289                 \DWATextension(reference to 20\$)
1290                 \DWTAGimportedmodule         ! (6) using directive
1291                     \DWATimport(reference to 40\$)
1292                 \DWTAGvariable
1293                     \DWATname("k")
1294                     \DWATtype(reference to 1\$)
1295                     \DWATlocation ...
1296                     ...
1297 60\$: \DWTAGsubprogram
1298         \DWATspecification(reference to 34\$)
1299         \DWATlowpc ...
1300         \DWAThighpc ...
1301         ...
1302 \end{alltt}
1303 \end{dwflisting}
1304 \begin{center}
1305 \vspace{3mm}
1306 Figure~\ref{fig:namespaceexampledwarfdescription}: Namespace example: DWARF description \textit{(concluded)}
1307 \end{center}
1308 \end{figure}
1309
1310 \clearpage
1311 \section{Member Function Examples}
1312 \label{app:memberfunctionexample}
1313 \addtoindexx{member function example}
1314 Consider the member function example fragment in 
1315 Figure \refersec{fig:memberfunctionexamplesourcefragment}.
1316 The DWARF representation in 
1317 Figure \refersec{fig:memberfunctionexampledwarfdescription}
1318 is appropriate.
1319
1320 \begin{figure}[h]
1321 \begin{lstlisting}
1322 class A
1323 {
1324     void func1(int x1);
1325     void func2() const;
1326     static void func3(int x3);
1327 };
1328 void A::func1(int x) {}
1329 \end{lstlisting}
1330 \caption{Member function example: source fragment}
1331 \label{fig:memberfunctionexamplesourcefragment}
1332 \end{figure}
1333
1334 \begin{figure}[h]
1335 \figurepart{1}{2}
1336 \begin{dwflisting}
1337 \begin{alltt}
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             \DWATobjectpointer(reference to 8\$) \addtoindexx{object pointer attribute}
1359                 ! References a formal parameter in this 
1360                 ! member function
1361             ...
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
1374 8\$:         \DWTAGformalparameter
1375                 \DWATartificial(true)
1376                 \DWATname("this")
1377                 \DWATtype(reference to 4\$)
1378                     ! Makes type of 'this' as 'A*' =>
1379                     ! func1 has not been marked const 
1380                     ! or volatile
1381                 \DWATlocation ...
1382                 ...
1383 9\$:         \DWTAGformalparameter
1384                 \DWATname(x1)
1385                 \DWATtype(reference to 2\$)
1386                 ...
1387 10\$:    \DWTAGsubprogram
1388             \DWATdeclaration
1389             \DWATname("func2")
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             ...
1406                 ! No object pointer reference formal parameter
1407                 ! implies func3 is static
1408 13\$:        \DWTAGformalparameter
1409                 \DWATname(x3)
1410                 \DWATtype(reference to 2\$)
1411                 ...
1412
1413 \end{alltt}
1414 \end{dwflisting}
1415 \begin{center}
1416 \vspace{3mm}
1417 Figure~\ref{fig:memberfunctionexampledwarfdescription}: Member function example: DWARF description \textit{(concluded)}
1418 \end{center}
1419 \end{figure}
1420
1421 \clearpage
1422 As a further example illustrating \&- and \&\&-qualification
1423 of member functions, 
1424 consider the member function example fragment in 
1425 Figure \refersec{fig:memberfunctionrefqualexamplesourcefragment}.
1426 The DWARF representation in 
1427 Figure \refersec{fig:memberfunctionrefqualexampledwarfdescription}
1428 is appropriate.
1429
1430 \begin{figure}[h]
1431 \begin{lstlisting}
1432 class A {
1433 public:
1434     void f() const &&;
1435 };
1436    
1437 void g() {
1438     A a;
1439     // The type of pointer is "void (A::*)() const &&".
1440     auto pointer_to_member_function = &A::f;
1441 }
1442 \end{lstlisting}
1443 \caption{Reference- and rvalue-reference-qualification example: source \mbox{fragment}}
1444 \label{fig:memberfunctionrefqualexamplesourcefragment}
1445 \end{figure}
1446
1447 \begin{figure}[h]
1448 %\figurepart{1}{2}
1449 \begin{dwflisting}
1450 \begin{alltt}
1451
1452 100$:   \DWTAGclasstype
1453             \DWATname("A")
1454             \DWTAGsubprogram
1455                 \DWATname("f")
1456                 \DWATrvaluereference(0x01)
1457                 \DWTAGformalparameter
1458                     \DWATtype({ref to 200$})    ! to const A*
1459                     \DWATartificial(0x01)
1460
1461 200$:   ! const A*
1462         \DWTAGpointertype
1463             \DWATtype({ref to 300$})             ! to const A
1464
1465 300$:   ! const A
1466         \DWTAGconsttype
1467             \DWATtype({ref to 100$})             ! to class A
1468
1469 400$:   ! mfptr
1470         \DWTAGptrtomembertype
1471             \DWATtype({ref to 400$})             ! to functype
1472             \DWATcontainingtype({ref to 100$})  ! to class A
1473
1474 500$:   ! functype
1475         \DWTAGsubroutinetype
1476             \DWATrvaluereference(0x01)
1477             \DWTAGformalparameter
1478                 \DWATtype({ref to 200$})         ! to const A*
1479                 \DWATartificial(0x01)
1480
1481 600$:   \DWTAGsubprogram
1482             \DWATname("g")
1483             \DWTAGvariable
1484                 \DWATname("a")
1485                 \DWATtype({ref to 100$})         ! to class A
1486             \DWTAGvariable
1487                 \DWATname("pointer_to_member_function")
1488                 \DWATtype({ref to 300$})
1489          
1490 \end{alltt}
1491 \end{dwflisting}
1492 \caption{Reference- and rvalue-reference-qualification example: DWARF \mbox{description}}
1493 \label{fig:memberfunctionrefqualexampledwarfdescription}
1494 \end{figure}
1495
1496
1497 \clearpage
1498 \section{Line Number Program Example}
1499 \label{app:linenumberprogramexample}
1500
1501 Consider the simple source file and the resulting machine
1502 code for the Intel 8086 processor in 
1503 Figure \refersec{fig:linenumberprogramexamplemachinecode}.
1504
1505 \begin{figure}[here]
1506 \begin{lstlisting}
1507 1: int
1508 2: main()
1509     0x239: push pb
1510     0x23a: mov bp,sp
1511 3: {
1512 4: printf("Omit needless words\n");
1513     0x23c: mov ax,0xaa
1514     0x23f: push ax
1515     0x240: call _printf
1516     0x243: pop cx
1517 5: exit(0);
1518     0x244: xor ax,ax
1519     0x246: push ax
1520     0x247: call _exit
1521     0x24a: pop cx
1522 6: }
1523     0x24b: pop bp
1524     0x24c: ret
1525 7: 0x24d:
1526 \end{lstlisting}
1527 \caption{Line number program example: machine code}
1528 \label{fig:linenumberprogramexamplemachinecode}
1529 \end{figure}
1530
1531 Suppose the line number program header includes the following
1532 (header fields not needed 
1533 \addttindexx{line\_base}
1534 below 
1535 \addttindexx{line\_range}
1536 are 
1537 \addttindexx{opcode\_base}
1538 not 
1539 \addttindexx{minimum\_instruction\_length}
1540 shown):
1541 \begin{alltt}
1542     version                       4
1543     minimum_instruction_length    1
1544     opcode_base                  10   ! Opcodes 10-12 not needed
1545     line_base                     1
1546     line_range                   15
1547 \end{alltt}
1548
1549
1550 Table \refersec{tab:linenumberprogramexampleoneencoding}
1551 shows one encoding of the line number program, which occupies
1552 12 bytes (the opcode SPECIAL(\textit{m},\textit{n}) indicates the special opcode
1553 generated for a line increment of \textit{m} and an address increment
1554 of \textit{n}).
1555
1556 \newpage
1557 \begin{centering}
1558 \setlength{\extrarowheight}{0.1cm}
1559 \begin{longtable}{l|l|l}
1560   \caption{Line number program example: one \mbox{encoding}}
1561   \label{tab:linenumberprogramexampleoneencoding} \\
1562   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
1563 \endfirsthead
1564   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
1565 \endhead
1566   \hline \emph{Continued on next page}
1567 \endfoot
1568   \hline
1569 \endlastfoot
1570 \DWLNSadvancepc&LEB128(0x239)&0x2, 0xb9, 0x04 \\
1571 SPECIAL(2, 0)& &0xb  \\
1572 SPECIAL(2, 3)& &0x38 \\
1573 SPECIAL(1, 8)& &0x82 \\
1574 SPECIAL(1, 7)& &0x73 \\
1575 \DWLNSadvancepc&LEB128(2)&0x2, 0x2 \\
1576 \DWLNEendsequence{} &&0x0, 0x1, 0x1 \\
1577 \end{longtable}
1578 \end{centering}
1579
1580
1581 Table \refersec{tab:linenumberprogramexamplealternateencoding}
1582 shows an alternate 
1583 encoding of the same program using 
1584 standard opcodes to advance
1585 the program counter; 
1586 this encoding occupies 22 bytes.
1587
1588 \begin{centering}
1589 \setlength{\extrarowheight}{0.1cm}
1590 \begin{longtable}{l|l|l}
1591   \caption{Line number program example: alternate encoding} 
1592   \label{tab:linenumberprogramexamplealternateencoding} \\
1593   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
1594 \endfirsthead
1595   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
1596 \endhead
1597   \hline \emph{Continued on next page}
1598 \endfoot
1599   \hline
1600 \endlastfoot
1601 \DWLNSfixedadvancepc&0x239&0x9, 0x39, 0x2        \\
1602 SPECIAL(2, 0)&& 0xb        \\
1603 \DWLNSfixedadvancepc&0x3&0x9, 0x3, 0x0        \\
1604 SPECIAL(2, 0)&&0xb        \\
1605 \DWLNSfixedadvancepc&0x8&0x9, 0x8, 0x0        \\
1606 SPECIAL(1, 0)&& 0xa        \\
1607 \DWLNSfixedadvancepc&0x7&0x9, 0x7, 0x0        \\
1608 SPECIAL(1, 0) && 0xa        \\
1609 \DWLNSfixedadvancepc&0x2&0x9, 0x2, 0x0        \\
1610 \DWLNEendsequence&&0x0, 0x1, 0x1        \\
1611 \end{longtable}
1612 \end{centering}
1613
1614 \needlines{6}
1615 \section{Call Frame Information Example}
1616 \label{app:callframeinformationexample}
1617
1618 The following example uses a hypothetical RISC machine in
1619 the style of the Motorola 88000.
1620 \begin{itemize}
1621 \item Memory is byte addressed.
1622
1623 \item Instructions are all 4 bytes each and word aligned.
1624
1625 \item Instruction operands are typically of the form:
1626 \begin{alltt}
1627     <destination.reg>, <source.reg>, <constant>
1628 \end{alltt}
1629
1630 \item The address for the load and store instructions is computed
1631 by adding the contents of the
1632 source register with the constant.
1633
1634 \item There are eight 4\dash byte registers:
1635 \newline
1636 \begin{tabular}{p{5mm}l}
1637    & R0 always 0 \\
1638    & R1 holds return address on call \\
1639    & R2-R3 temp registers (not preserved on call) \\
1640    & R4-R6 preserved on call \\
1641    & R7 stack pointer \\
1642 \end{tabular}
1643
1644 \item  The stack grows in the negative direction.
1645
1646 \item The architectural ABI committee specifies that the
1647 stack pointer (R7) is the same as the CFA
1648
1649 \end{itemize}
1650
1651 Figure \referfol{fig:callframeinformationexamplemachinecodefragments}
1652 shows two code fragments from a subroutine called
1653 foo that uses a frame pointer (in addition to the stack
1654 pointer). The first column values are byte addresses. 
1655 % The \space is so we get a space after >
1656 \textless fs\textgreater\ denotes the stack frame size in bytes, namely 12.
1657
1658
1659 \begin{figure}[here]
1660 \begin{lstlisting}
1661        ;; start prologue
1662 foo    sub   R7, R7, <fs>        ; Allocate frame
1663 foo+4  store R1, R7, (<fs>-4)    ; Save the return address
1664 foo+8  store R6, R7, (<fs>-8)    ; Save R6
1665 foo+12 add   R6, R7, 0           ; R6 is now the Frame ptr
1666 foo+16 store R4, R6, (<fs>-12)   ; Save a preserved reg
1667        ;; This subroutine does not change R5
1668        ...
1669        ;; Start epilogue (R7 is returned to entry value)
1670 foo+64 load  R4, R6, (<fs>-12)   ; Restore R4
1671 foo+68 load  R6, R7, (<fs>-8)    ; Restore R6
1672 foo+72 load  R1, R7, (<fs>-4)    ; Restore return address
1673 foo+76 add   R7, R7, <fs>        ; Deallocate frame
1674 foo+80 jump  R1                  ; Return
1675 foo+84
1676 \end{lstlisting}
1677 \caption{Call frame information example: machine code fragments}
1678 \label{fig:callframeinformationexamplemachinecodefragments}
1679 \end{figure}
1680
1681
1682 An abstract table 
1683 (see Section \refersec{chap:structureofcallframeinformation}) 
1684 for the foo subroutine is shown in 
1685 Table \referfol{tab:callframeinformationexampleconceptualmatrix}.
1686 Corresponding fragments from the
1687 \dotdebugframe{} section are shown in 
1688 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
1689
1690 The following notations apply in 
1691 Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
1692 \newline
1693 \begin{tabular}{p{5mm}l}
1694 &1.  R8 is the return address \\
1695 &2.  s = same\_value rule \\
1696 &3.  u = undefined rule \\
1697 &4.  rN = register(N) rule \\
1698 &5.  cN = offset(N) rule \\
1699 &6.  a = architectural rule \\
1700 \end{tabular}
1701
1702 \begin{centering}
1703 \setlength{\extrarowheight}{0.1cm}
1704 \begin{longtable}{l|llllllllll}
1705   \caption{Call frame information example: conceptual matrix} 
1706   \label{tab:callframeinformationexampleconceptualmatrix} \\
1707   \hline \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
1708 \endfirsthead
1709   \bfseries Location &\bfseries CFA &\bfseries R0 & \bfseries R1 & \bfseries R2 &\bfseries R3 &\bfseries R4 &\bfseries R5 &\bfseries R6 &\bfseries R7 &\bfseries R8\\ \hline
1710 \endhead
1711   \hline \emph{Continued on next page}
1712 \endfoot
1713   \hline
1714 \endlastfoot
1715 foo&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
1716 foo+4&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
1717 foo+8&[R7]+fs&s&u&u&u&s&s&s&a&c-4 \\
1718 foo+12&[R7]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
1719 foo+16&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
1720 foo+20&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
1721 ...&&&&&&&&&& \\
1722 foo+64&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
1723 foo+68&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4  \\
1724 foo+72&[R7]+fs&s&u&u&u&s&s&s&a&c-4  \\
1725 foo+76&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
1726 foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
1727 \end{longtable}
1728 \end{centering}
1729
1730 \clearpage      % ?????
1731
1732 \begin{centering}
1733 \setlength{\extrarowheight}{0.1cm}
1734 \begin{longtable}{l|ll}
1735   \caption{Call frame information example: common information entry encoding} 
1736   \label{tab:callframeinformationexamplecommoninformationentryencoding} 
1737   \\
1738   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1739 \endfirsthead
1740   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1741 \endhead
1742   \hline \emph{Continued on next page}
1743 \endfoot
1744   \hline
1745 \endlastfoot
1746 cie&36&length    \\
1747 cie+4&\xffffffff&CIE\_id    \\
1748 cie+8&4&version    \\
1749 cie+9&0&augmentation     \\
1750 cie+10&4&address size    \\
1751 cie+11&0&segment size    \\
1752 cie+12&4&code\_alignment\_factor, \textless caf \textgreater    \\
1753 cie+13&-4&data\_alignment\_factor, \textless daf \textgreater    \\
1754 cie+14&8&R8 is the return addr.    \\
1755 cie+15&\DWCFAdefcfa{} (7, 0)&CFA = [R7]+0    \\
1756 cie+18&\DWCFAsamevalue{} (0)&R0 not modified (=0)    \\
1757 cie+20&\DWCFAundefined{} (1)&R1 scratch    \\
1758 cie+22&\DWCFAundefined{} (2)&R2 scratch    \\
1759 cie+24&\DWCFAundefined{} (3)&R3 scratch    \\
1760 cie+26&\DWCFAsamevalue{} (4)&R4 preserve    \\
1761 cie+28&\DWCFAsamevalue{} (5)&R5 preserve    \\
1762 cie+30&\DWCFAsamevalue{} (6)&R6 preserve    \\
1763 cie+32&\DWCFAsamevalue{} (7)&R7 preserve    \\
1764 cie+34&\DWCFAregister{} (8, 1)&R8 is in R1    \\
1765 cie+37&\DWCFAnop{} &padding    \\
1766 cie+38&\DWCFAnop{} &padding \\
1767 cie+39& \DWCFAnop&padding  \\
1768 cie+40 &&  \\
1769 \end{longtable}
1770 \end{centering}
1771
1772
1773 The following notations apply in 
1774 Table \refersec{tab:callframeinformationexampleframedescriptionentryencoding}:
1775 \newline
1776 \begin{tabular}{p{5mm}l}
1777 &\texttt{<fs>  =} frame size \\
1778 &\texttt{<caf> =} code alignment factor \\
1779 &\texttt{<daf> =} data alignment factor \\
1780 \end{tabular}
1781
1782
1783 \begin{centering}
1784 \setlength{\extrarowheight}{0.1cm}
1785 \begin{longtable}{l|ll}
1786   \caption{Call frame information example: frame description entry encoding} 
1787   \label{tab:callframeinformationexampleframedescriptionentryencoding} \\
1788   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1789 \endfirsthead
1790   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1791 \endhead
1792   \hline \emph{Continued on next page}
1793 \endfoot
1794   \hline
1795 \endlastfoot
1796 fde&40&length \\
1797 fde+4&cie&CIE\_ptr \\
1798 fde+8&foo&initial\_location \\
1799 fde+12&84&address\_range \\
1800 fde+16&\DWCFAadvanceloc(1)&instructions \\
1801 fde+17&\DWCFAdefcfaoffset(12)& \textless fs\textgreater \\
1802 fde+19&\DWCFAadvanceloc(1)&4/\textless caf\textgreater \\
1803 fde+20&\DWCFAoffset(8,1)&-4/\textless daf\textgreater (2nd parameter) \\
1804 fde+22&\DWCFAadvanceloc(1)& \\
1805 fde+23&\DWCFAoffset(6,2)&-8/\textless daf\textgreater (2nd parameter)  \\
1806 fde+25&\DWCFAadvanceloc(1) & \\
1807 fde+26&\DWCFAdefcfaregister(6) & \\
1808 fde+28&\DWCFAadvanceloc(1) & \\
1809 fde+29&\DWCFAoffset(4,3)&-12/\textless daf\textgreater (2nd parameter) \\
1810 fde+31&\DWCFAadvanceloc(12)&44/\textless caf\textgreater \\
1811 fde+32&\DWCFArestore(4)& \\
1812 fde+33&\DWCFAadvanceloc(1) & \\
1813 fde+34&\DWCFArestore(6) & \\
1814 fde+35&\DWCFAdefcfaregister(7)  & \\
1815 fde+37&\DWCFAadvanceloc(1) & \\
1816 fde+38&\DWCFArestore(8) &\\
1817 fde+39&\DWCFAadvanceloc(1) &\\
1818 fde+40&\DWCFAdefcfaoffset(0)  &\\
1819 fde+42&\DWCFAnop&padding \\
1820 fde+43&\DWCFAnop&padding \\
1821 fde+44 && \\
1822 \end{longtable}
1823 \end{centering}
1824
1825 \section{Inlining Examples}
1826 \label{app:inliningexamples}
1827 The pseudo\dash source in 
1828 Figure \referfol{fig:inliningexamplespseudosourcefragment}
1829 is used to illustrate the
1830 \addtoindexx{inlined subprogram call!examples}
1831 use of DWARF to describe inlined subroutine calls. This
1832 example involves a nested subprogram \texttt{INNER} that makes uplevel
1833 references to the formal parameter and local variable of the
1834 containing subprogram \texttt{OUTER}.
1835
1836 \begin{figure}[here]
1837 \begin{lstlisting}
1838 inline procedure OUTER (OUTER_FORMAL : integer) =
1839     begin
1840     OUTER_LOCAL : integer;
1841     procedure INNER (INNER_FORMAL : integer) =
1842         begin
1843         INNER_LOCAL : integer;
1844         print(INNER_FORMAL + OUTER_LOCAL);
1845         end;
1846     INNER(OUTER_LOCAL);
1847     ...
1848     INNER(31);
1849     end;
1850 ! Call OUTER
1851 !
1852 OUTER(7);
1853 \end{lstlisting}
1854 \caption{Inlining examples: pseudo-source fragmment} 
1855 \label{fig:inliningexamplespseudosourcefragment}
1856 \end{figure}
1857
1858
1859 There are several approaches that a compiler might take to
1860 inlining for this sort of example. This presentation considers
1861 three such approaches, all of which involve inline expansion
1862 of subprogram \texttt{OUTER}. (If \texttt{OUTER} is not inlined, the inlining
1863 reduces to a simpler single level subset of the two level
1864 approaches considered here.)
1865
1866 The approaches are:
1867 \begin{enumerate}[1. ]
1868 \item  Inline both \texttt{OUTER} and \texttt{INNER} in all cases
1869
1870 \item Inline \texttt{OUTER}, multiple \texttt{INNER}s \\
1871 Treat \texttt{INNER} as a non\dash inlinable part of \texttt{OUTER}, compile and
1872 call a distinct normal version of \texttt{INNER} defined within each
1873 inlining of \texttt{OUTER}.
1874
1875 \item Inline \texttt{OUTER}, one \texttt{INNER} \\
1876 Compile \texttt{INNER} as a single normal subprogram which is called
1877 from every inlining of \texttt{OUTER}.
1878 \end{enumerate}
1879
1880 This discussion does not consider why a compiler might choose
1881 one of these approaches; it considers only how to describe
1882 the result.
1883
1884 In the examples that follow in this section, the debugging
1885 information entries are given mnemonic labels of the following
1886 form
1887 \begin{verbatim}
1888     <io>.<ac>.<n>.<s>
1889 \end{verbatim}
1890 where
1891 \begin{description}
1892 \item[\textless io\textgreater]
1893 is either \texttt{INNER} or \texttt{OUTER} to indicate to which
1894 subprogram the debugging information entry applies, 
1895 \item[\textless ac\textgreater]
1896 is either AI or CI to indicate \doublequote{abstract instance} or
1897 \doublequote{concrete instance} respectively, 
1898 \item[\textless n\textgreater]
1899 is the number of the
1900 alternative being considered, and 
1901 \item[\textless s\textgreater]
1902 is a sequence number that
1903 distinguishes the individual entries. 
1904 \end{description}
1905 There is no implication
1906 that symbolic labels, nor any particular naming convention,
1907 are required in actual use.
1908
1909 For conciseness, declaration coordinates and call coordinates are omitted.
1910
1911 \subsection{Alternative \#1: inline both OUTER and INNER}
1912 \label{app:inlinebothouterandinner}
1913
1914 A suitable abstract instance for an alternative where both
1915 \texttt{OUTER} and \texttt{INNER} are always inlined is shown in 
1916 Figure \refersec{fig:inliningexample1abstractinstance}.
1917
1918 Notice in 
1919 Figure \ref{fig:inliningexample1abstractinstance} 
1920 that the debugging information entry for
1921 \texttt{INNER} (labelled \texttt{INNER.AI.1.1}) is nested in (is a child of)
1922 that for \texttt{OUTER} (labelled \texttt{OUTER.AI.1.1}). Nonetheless, the
1923 abstract instance tree for \texttt{INNER} is considered to be separate
1924 and distinct from that for \texttt{OUTER}.
1925
1926 The call of \texttt{OUTER} shown in 
1927 Figure \refersec{fig:inliningexamplespseudosourcefragment}
1928 might be described as
1929 shown in 
1930 Figure \refersec{fig:inliningexample1concreteinstance}.
1931
1932
1933 \begin{figure}[p]
1934 \begin{dwflisting}
1935 \begin{alltt}
1936     ! Abstract instance for OUTER
1937     ! \addtoindexx{abstract instance!example}
1938 OUTER.AI.1.1:
1939     \DWTAGsubprogram
1940         \DWATname("OUTER")
1941         \DWATinline(\DWINLdeclaredinlined)
1942         ! No low/high PCs
1943 OUTER.AI.1.2:
1944         \DWTAGformalparameter
1945             \DWATname("OUTER\_FORMAL")
1946             \DWATtype(reference to integer)
1947             ! No location
1948 OUTER.AI.1.3:
1949         \DWTAGvariable
1950             \DWATname("OUTER\_LOCAL")
1951             \DWATtype(reference to integer)
1952             ! No location
1953         !
1954         ! Abstract instance for INNER
1955         !
1956 INNER.AI.1.1:
1957         \DWTAGsubprogram
1958             \DWATname("INNER")
1959             \DWATinline(\DWINLdeclaredinlined)
1960             ! No low/high PCs
1961 INNER.AI.1.2:
1962             \DWTAGformalparameter
1963                 \DWATname("INNER\_FORMAL")
1964                 \DWATtype(reference to integer)
1965                 ! No location
1966 INNER.AI.1.3:
1967             \DWTAGvariable
1968                 \DWATname("INNER\_LOCAL")
1969                 \DWATtype(reference to integer)
1970                 ! No location
1971             ...
1972             0
1973         ! No \DWTAGinlinedsubroutine (concrete instance)
1974         ! for INNER corresponding to calls of INNER
1975         ...
1976         0
1977 \end{alltt}
1978 \end{dwflisting}
1979 \caption{Inlining example \#1: abstract instance}
1980 \label{fig:inliningexample1abstractinstance}
1981 \end{figure}
1982
1983 \begin{figure}[p]
1984 \begin{dwflisting}
1985 \begin{alltt}
1986 ! Concrete instance for call "OUTER(7)"
1987 ! \addtoindexx{concrete instance!example}
1988 OUTER.CI.1.1:
1989     \DWTAGinlinedsubroutine
1990         ! No name
1991         \DWATabstractorigin(reference to OUTER.AI.1.1)
1992         \DWATlowpc(...)
1993         \DWAThighpc(...)
1994 OUTER.CI.1.2:
1995         \DWTAGformalparameter
1996             ! No name
1997             \DWATabstractorigin(reference to OUTER.AI.1.2)
1998             \DWATconstvalue(7)
1999 OUTER.CI.1.3:
2000         \DWTAGvariable
2001             ! No name
2002             \DWATabstractorigin(reference to OUTER.AI.1.3)
2003             \DWATlocation(...)
2004         !
2005         ! No \DWTAGsubprogram (abstract instance) for INNER
2006         !
2007         ! Concrete instance for call INNER(OUTER\_LOCAL)
2008         !
2009 INNER.CI.1.1:
2010         \DWTAGinlinedsubroutine
2011             ! No name
2012             \DWATabstractorigin(reference to INNER.AI.1.1)
2013             \DWATlowpc(...)
2014             \DWAThighpc(...)
2015             \DWATstaticlink(...)
2016 INNER.CI.1.2:
2017             \DWTAGformalparameter
2018                 ! No name
2019                 \DWATabstractorigin(reference to INNER.AI.1.2)
2020                 \DWATlocation(...)
2021 INNER.CI.1.3:
2022             \DWTAGvariable
2023                 ! No name
2024                 \DWATabstractorigin(reference to INNER.AI.1.3)
2025                 \DWATlocation(...)
2026             ...
2027             0
2028         ! Another concrete instance of INNER within OUTER
2029         ! for the call "INNER(31)"
2030         ...
2031         0
2032 \end{alltt}
2033 \end{dwflisting}
2034 \caption{Inlining example \#1: concrete instance}
2035 \label{fig:inliningexample1concreteinstance}
2036 \end{figure}
2037
2038 \subsection{Alternative \#2: Inline OUTER, multiple INNERs}
2039 \label{app:inlineoutermultiipleinners}
2040
2041
2042 In the second alternative we assume that subprogram \texttt{INNER}
2043 is not inlinable for some reason, but subprogram \texttt{OUTER} is
2044 inlinable. 
2045 \addtoindexx{concrete instance!example}
2046 Each concrete inlined instance of \texttt{OUTER} has its
2047 own normal instance of \texttt{INNER}. 
2048 The abstract instance for \texttt{OUTER},
2049 \addtoindexx{abstract instance!example}
2050 which includes \texttt{INNER}, is shown in 
2051 Figure \refersec{fig:inliningexample2abstractinstance}.
2052
2053 Note that the debugging information in 
2054 Figure \ref{fig:inliningexample2abstractinstance}
2055 differs from that in 
2056 Figure \refersec{fig:inliningexample1abstractinstance}
2057 in that \texttt{INNER} lacks a 
2058 \DWATinline{} attribute
2059 and therefore is not a distinct abstract instance. \texttt{INNER}
2060 is merely an out\dash of\dash line routine that is part of \texttt{OUTER}\textquoteright s
2061 abstract instance. This is reflected in the Figure by
2062 \addtoindexx{abstract instance!example}
2063 the fact that the labels for \texttt{INNER} use the substring \texttt{OUTER}
2064 instead of \texttt{INNER}.
2065
2066 A resulting 
2067 \addtoindexx{concrete instance!example}
2068 concrete inlined instance of \texttt{OUTER} is shown in
2069 Figure \refersec{fig:inliningexample2concreteinstance}.
2070
2071 Notice in 
2072 Figure \ref{fig:inliningexample2concreteinstance}
2073 that \texttt{OUTER} is expanded as a concrete
2074 \addtoindexx{concrete instance!example}
2075 inlined instance, and that \texttt{INNER} is nested within it as a
2076 concrete out\dash of\dash line subprogram. Because \texttt{INNER} is cloned
2077 for each inline expansion of \texttt{OUTER}, only the invariant
2078 attributes of \texttt{INNER} 
2079 (for example, \DWATname) are specified
2080 in the abstract instance of \texttt{OUTER}, and the low\dash level,
2081 \addtoindexx{abstract instance!example}
2082 instance\dash specific attributes of \texttt{INNER} (for example,
2083 \DWATlowpc) are specified in 
2084 each concrete instance of \texttt{OUTER}.
2085 \addtoindexx{concrete instance!example}
2086
2087 The several calls of \texttt{INNER} within \texttt{OUTER} are compiled as normal
2088 calls to the instance of \texttt{INNER} that is specific to the same
2089 instance of \texttt{OUTER} that contains the calls.
2090
2091 \begin{figure}[t]
2092 \begin{dwflisting}
2093 \begin{alltt}
2094     ! Abstract instance for OUTER
2095     ! \addtoindex{abstract instance}
2096 OUTER.AI.2.1:
2097     \DWTAGsubprogram
2098         \DWATname("OUTER")
2099         \DWATinline(\DWINLdeclaredinlined)
2100         ! No low/high PCs
2101 OUTER.AI.2.2:
2102         \DWTAGformalparameter
2103             \DWATname("OUTER\_FORMAL")
2104             \DWATtype(reference to integer)
2105             ! No location
2106 OUTER.AI.2.3:
2107         \DWTAGvariable
2108             \DWATname("OUTER\_LOCAL")
2109             \DWATtype(reference to integer)
2110             ! No location
2111         !
2112         ! Nested out-of-line INNER subprogram
2113         !
2114 OUTER.AI.2.4:
2115         \DWTAGsubprogram
2116             \DWATname("INNER")
2117             ! No \DWATinline
2118             ! No low/high PCs, frame\_base, etc.
2119 OUTER.AI.2.5:
2120             \DWTAGformalparameter
2121                 \DWATname("INNER\_FORMAL")
2122                 \DWATtype(reference to integer)
2123                 ! No location
2124 OUTER.AI.2.6:
2125             \DWTAGvariable
2126                 \DWATname("INNER\_LOCAL")
2127                 \DWATtype(reference to integer)
2128                 ! No location
2129             ...
2130             0
2131         ...
2132         0
2133 \end{alltt}
2134 \end{dwflisting}
2135 \caption{Inlining example \#2: abstract instance}
2136 \label{fig:inliningexample2abstractinstance}
2137 \end{figure}
2138
2139 \begin{figure}[t]
2140 \begin{dwflisting}
2141 \begin{alltt}
2142
2143     ! Concrete instance for call "OUTER(7)"
2144     !
2145 OUTER.CI.2.1:
2146     \DWTAGinlinedsubroutine
2147         ! No name
2148         \DWATabstractorigin(reference to OUTER.AI.2.1)
2149         \DWATlowpc(...)
2150         \DWAThighpc(...)
2151 OUTER.CI.2.2:
2152         \DWTAGformalparameter
2153             ! No name
2154             \DWATabstractorigin(reference to OUTER.AI.2.2)
2155             \DWATlocation(...)
2156 OUTER.CI.2.3:
2157         \DWTAGvariable
2158             ! No name
2159             \DWATabstractorigin(reference to OUTER.AI.2.3)
2160             \DWATlocation(...)
2161         !
2162         ! Nested out-of-line INNER subprogram
2163         !
2164 OUTER.CI.2.4:
2165         \DWTAGsubprogram
2166             ! No name
2167             \DWATabstractorigin(reference to OUTER.AI.2.4)
2168             \DWATlowpc(...)
2169             \DWAThighpc(...)
2170             \DWATframebase(...)
2171             \DWATstaticlink(...)
2172 OUTER.CI.2.5:
2173             \DWTAGformalparameter
2174                 ! No name
2175                 \DWATabstractorigin(reference to OUTER.AI.2.5)
2176                 \DWATlocation(...)
2177 OUTER.CI.2.6:
2178             \DWTAGvariable
2179                 ! No name
2180                 \DWATabstractorigin(reference to OUTER.AT.2.6)
2181                 \DWATlocation(...)
2182             ...
2183             0
2184         ...
2185         0
2186 \end{alltt}
2187 \end{dwflisting}
2188 \caption{Inlining example \#2: concrete instance}
2189 \label{fig:inliningexample2concreteinstance}
2190 \end{figure}
2191
2192 \subsection{Alternative \#3: inline OUTER, one normal INNER}
2193 \label{app:inlineouteronenormalinner}
2194
2195 In the third approach, one normal subprogram for \texttt{INNER} is
2196 compiled which is called from all concrete inlined instances of
2197 \addtoindexx{concrete instance!example}
2198 \addtoindexx{abstract instance!example}
2199 \texttt{OUTER}. The abstract instance for \texttt{OUTER} is shown in 
2200 Figure \refersec{fig:inliningexample3abstractinstance}.
2201
2202 The most distinctive aspect of that Figure is that subprogram
2203 \texttt{INNER} exists only within the abstract instance of \texttt{OUTER},
2204 and not in \texttt{OUTER}\textquoteright s concrete instance. In the abstract
2205 \addtoindexx{concrete instance!example}
2206 \addtoindexx{abstract instance!example}
2207 instance of \texttt{OUTER}, the description of \texttt{INNER} has the full
2208 complement of attributes that would be expected for a
2209 normal subprogram. 
2210 While attributes such as 
2211 \DWATlowpc,
2212 \DWAThighpc, 
2213 \DWATlocation,
2214 and so on, typically are omitted
2215 \addtoindexx{high PC attribute}
2216 from 
2217 \addtoindexx{low PC attribute}
2218 an 
2219 \addtoindexx{location attribute}
2220 abstract instance because they are not invariant across
2221 instances of the containing abstract instance, in this case
2222 those same attributes are included precisely because they are
2223 invariant -- there is only one subprogram \texttt{INNER} to be described
2224 and every description is the same.
2225
2226 A concrete inlined instance of \texttt{OUTER} is illustrated in
2227 Figure \refersec{fig:inliningexample3concreteinstance}.
2228
2229 Notice in 
2230 Figure \ref{fig:inliningexample3concreteinstance}
2231 that there is no DWARF representation for
2232 \texttt{INNER} at all; the representation of \texttt{INNER} does not vary across
2233 instances of \texttt{OUTER} and the abstract instance of \texttt{OUTER} includes
2234 the complete description of \texttt{INNER}, so that the description of
2235 \texttt{INNER} may be (and for reasons of space efficiency, should be)
2236 omitted from each 
2237 \addtoindexx{concrete instance!example}
2238 concrete instance of \texttt{OUTER}.
2239
2240 There is one aspect of this approach that is problematical from
2241 the DWARF perspective. The single compiled instance of \texttt{INNER}
2242 is assumed to access up\dash level variables of \texttt{OUTER}; however,
2243 those variables may well occur at varying positions within
2244 the frames that contain the 
2245 \addtoindexx{concrete instance!example}
2246 concrete inlined instances. A
2247 compiler might implement this in several ways, including the
2248 use of additional compiler-generated parameters that provide
2249 reference parameters for the up\dash level variables, or a 
2250 compiler-generated static link like parameter that points to the group
2251 of up\dash level entities, among other possibilities. In either of
2252 these cases, the DWARF description for the location attribute
2253 of each uplevel variable needs to be different if accessed
2254 from within \texttt{INNER} compared to when accessed from within the
2255 instances of \texttt{OUTER}. An implementation is likely to require
2256 vendor\dash specific DWARF attributes and/or debugging information
2257 entries to describe such cases.
2258
2259 Note that in \addtoindex{C++}, a member function of a class defined within
2260 a function definition does not require any vendor\dash specific
2261 extensions because the \addtoindex{C++} language disallows access to
2262 entities that would give rise to this problem. (Neither \texttt{extern}
2263 variables nor \texttt{static} members require any form of static link
2264 for accessing purposes.)
2265
2266 \begin{figure}[t]
2267 \begin{dwflisting}
2268 \begin{alltt}
2269     ! Abstract instance for OUTER
2270     ! \addtoindexx{abstract instance!example}
2271 OUTER.AI.3.1:
2272     \DWTAGsubprogram
2273         \DWATname("OUTER")
2274         \DWATinline(\DWINLdeclaredinlined)
2275         ! No low/high PCs
2276 OUTER.AI.3.2:
2277         \DWTAGformalparameter
2278             \DWATname("OUTER\_FORMAL")
2279             \DWATtype(reference to integer)
2280             ! No location
2281 OUTER.AI.3.3:
2282         \DWTAGvariable
2283             \DWATname("OUTER\_LOCAL")
2284             \DWATtype(reference to integer)
2285             ! No location
2286         !
2287         ! Normal INNER
2288         !
2289 OUTER.AI.3.4:
2290         \DWTAGsubprogram
2291             \DWATname("INNER")
2292             \DWATlowpc(...)
2293             \DWAThighpc(...)
2294             \DWATframebase(...)
2295             \DWATstaticlink(...)
2296 OUTER.AI.3.5:
2297             \DWTAGformalparameter
2298                 \DWATname("INNER\_FORMAL")
2299                 \DWATtype(reference to integer)
2300                 \DWATlocation(...)
2301 OUTER.AI.3.6:
2302             \DWTAGvariable
2303                 \DWATname("INNER\_LOCAL")
2304                 \DWATtype(reference to integer)
2305                 \DWATlocation(...)
2306             ...
2307             0
2308         ...
2309         0
2310 \end{alltt}
2311 \end{dwflisting}
2312 \caption{Inlining example \#3: abstract instance}
2313 \label{fig:inliningexample3abstractinstance}
2314 \end{figure}
2315
2316 \begin{figure}[t]
2317 \begin{dwflisting}
2318 \begin{alltt}
2319     ! Concrete instance for call "OUTER(7)"
2320     ! \addtoindexx{concrete instance!example}
2321 OUTER.CI.3.1:
2322     \DWTAGinlinedsubroutine
2323         ! No name
2324         \DWATabstractorigin(reference to OUTER.AI.3.1)
2325         \DWATlowpc(...)
2326         \DWAThighpc(...)
2327         \DWATframebase(...)
2328 OUTER.CI.3.2:
2329         \DWTAGformalparameter
2330             ! No name
2331             \DWATabstractorigin(reference to OUTER.AI.3.2)
2332             ! No type
2333             \DWATlocation(...)
2334 OUTER.CI.3.3:
2335         \DWTAGvariable
2336             ! No name
2337             \DWATabstractorigin(reference to OUTER.AI.3.3)
2338             ! No type
2339             \DWATlocation(...)
2340         ! No \DWTAGsubprogram for "INNER"
2341         ...
2342         0
2343 \end{alltt}
2344 \end{dwflisting}
2345 \caption{Inlining example \#3: concrete instance}
2346 \label{fig:inliningexample3concreteinstance}
2347 \end{figure}
2348
2349 \clearpage
2350 \section{Constant Expression Example}
2351 \label{app:constantexpressionexample}
2352 \addtoindex{C++} generalizes the notion of constant expressions to include
2353 constant expression user-defined literals and functions.
2354 The constant declarations in Figure \refersec{fig:constantexpressionscsource}
2355 can be represented as illustrated in 
2356 Figure \refersec{fig:constantexpressionsdwarfdescription}.
2357
2358
2359 \begin{figure}[here]
2360 \begin{lstlisting}[numbers=none]
2361 constexpr double mass = 9.8;
2362 constexpr int square (int x) { return x * x; }
2363 float arr[square(9)]; // square() called and inlined
2364 \end{lstlisting}
2365 \caption{Constant expressions: C++ source} \label{fig:constantexpressionscsource}
2366 \end{figure}
2367
2368
2369 \begin{figure}[!h]
2370 \begin{dwflisting}
2371 \begin{alltt}
2372         ! For variable mass
2373         !
2374 1\$:     \DWTAGconsttype
2375             \DWATtype(reference to "double")
2376 2\$:     \DWTAGvariable
2377             \DWATname("mass")
2378             \DWATtype(reference to 1\$)
2379             \DWATconstexpr(true)
2380             \DWATconstvalue(9.8)
2381         ! Abstract instance for square
2382         !
2383 10\$:    \DWTAGsubprogram
2384             \DWATname("square")
2385             \DWATtype(reference to "int")
2386             \DWATinline(\DWINLinlined)
2387 11\$:        \DWTAGformalparameter
2388                 \DWATname("x")
2389                 \DWATtype(reference to "int")
2390         ! Concrete instance for square(9)
2391         ! \addtoindexx{concrete instance!example}
2392 20\$:    \DWTAGinlinedsubroutine
2393             \DWATabstractorigin(reference to 10\$)
2394             \DWATconstexpr(present)
2395             \DWATconstvalue(81)
2396             \DWTAGformalparameter
2397                 \DWATabstractorigin(reference to 11\$)
2398                 \DWATconstvalue(9)
2399         ! Anonymous array type for arr
2400         !
2401 30\$:    \DWTAGarraytype
2402             \DWATtype(reference to "float")
2403             \DWATbytesize(324) ! 81*4
2404             \DWTAGsubrangetype
2405                 \DWATtype(reference to "int")
2406                 \DWATupperbound(reference to 20\$)
2407         ! Variable arr
2408         !
2409 40\$:    \DWTAGvariable
2410             \DWATname("arr")
2411             \DWATtype(reference to 30\$)
2412 \end{alltt}
2413 \end{dwflisting}
2414 \caption{Constant expressions: DWARF description}
2415 \label{fig:constantexpressionsdwarfdescription}
2416 \end{figure}
2417
2418 \section{Unicode Character Example}
2419 \label{app:unicodecharacterexample}
2420 \addtoindexx{Unicode|see {\textit{also} UTF-8}}
2421 The \addtoindex{Unicode} character encodings in
2422 Figure \refersec{fig:unicodecharacterexamplesource}
2423 can be described in DWARF as illustrated in 
2424 Figure \refersec{fig:unicodecharacterexampledwarfdescription}.
2425
2426 \begin{figure}[!h]
2427 \begin{lstlisting}[numbers=none]
2428 // C++ source
2429 //
2430 char16_t chr_a = u'h';
2431 char32_t chr_b = U'h';
2432 \end{lstlisting}
2433 \caption{Unicode character example: source}
2434 \label{fig:unicodecharacterexamplesource}
2435 \end{figure}
2436
2437 \begin{figure}[h]
2438 \begin{dwflisting}
2439 \begin{alltt}
2440
2441 ! DWARF description
2442 !
2443 1\$: \DWTAGbasetype
2444         \DWATname("char16\_t")
2445         \DWATencoding(\DWATEUTF)
2446         \DWATbytesize(2)
2447 2\$: \DWTAGbasetype
2448         \DWATname("char32\_t")
2449         \DWATencoding(\DWATEUTF)
2450         \DWATbytesize(4)
2451 3\$: \DWTAGvariable
2452         \DWATname("chr\_a")
2453         \DWATtype(reference to 1\$)
2454 4\$: \DWTAGvariable
2455         \DWATname("chr\_b")
2456         \DWATtype(reference to 2\$)
2457 \end{alltt}
2458 \end{dwflisting}
2459 \caption{Unicode character example: DWARF description}
2460 \label{fig:unicodecharacterexampledwarfdescription}
2461 \end{figure}
2462
2463
2464 \section{Type-Safe Enumeration Example}
2465 \label{app:typesafeenumerationexample}
2466
2467 The \addtoindex{C++} type\dash safe enumerations in
2468 \addtoindexx{type-safe enumeration}
2469 Figure \refersec{fig:ctypesafeenumerationexamplesource}
2470 can be described in DWARF as illustrated in 
2471 Figure \refersec{fig:ctypesafeenumerationexampledwarf}.
2472
2473 \clearpage      % Get following source and DWARF on same page
2474
2475 \begin{figure}[H]
2476 \begin{lstlisting}[numbers=none]
2477 // C++ source
2478 //
2479 enum class E { E1, E2=100 };
2480 E e1;
2481 \end{lstlisting}
2482 \caption{Type-safe enumeration example: source}
2483 \label{fig:ctypesafeenumerationexamplesource}
2484 \end{figure}
2485
2486 \begin{figure}[H]
2487 \begin{dwflisting}
2488 \begin{alltt}
2489 ! DWARF description
2490 !
2491 11\$:  \DWTAGenumerationtype
2492           \DWATname("E")
2493           \DWATtype(reference to "int")
2494           \DWATenumclass(present)
2495 12\$:      \DWTAGenumerator
2496               \DWATname("E1")
2497               \DWATconstvalue(0)
2498 13\$:      \DWTAGenumerator
2499               \DWATname("E2")
2500               \DWATconstvalue(100)
2501 14\$:  \DWTAGvariable
2502          \DWATname("e1")
2503          \DWATtype(reference to 11\$)
2504 \end{alltt}
2505 \end{dwflisting}
2506 \caption{Type-safe enumeration example: DWARF description}
2507 \label{fig:ctypesafeenumerationexampledwarf}
2508 \end{figure}
2509
2510
2511 \clearpage
2512 \section{Template Examples}
2513 \label{app:templateexample}
2514
2515 The \addtoindex{C++} template example in
2516 Figure \refersec{fig:ctemplateexample1source}
2517 can be described in DWARF as illustrated in 
2518 Figure \refersec{fig:ctemplateexample1dwarf}.
2519
2520 \begin{figure}[h]
2521 \begin{lstlisting}
2522 // C++ source
2523 //
2524 template<class T>
2525 struct wrapper {
2526     T comp;
2527 };
2528 wrapper<int> obj;
2529 \end{lstlisting}
2530 \caption{C++ template example \#1: source}
2531 \label{fig:ctemplateexample1source}
2532 \end{figure}
2533
2534 \begin{figure}[h]
2535 \begin{dwflisting}
2536 \begin{alltt}
2537 ! DWARF description
2538 !
2539 11\$: \DWTAGstructuretype
2540         \DWATname("wrapper")
2541 12\$:    \DWTAGtemplatetypeparameter
2542             \DWATname("T")
2543             \DWATtype(reference to "int")
2544 13\$:    \DWTAGmember
2545             \DWATname("comp")
2546             \DWATtype(reference to 12\$)
2547 14\$: \DWTAGvariable
2548         \DWATname("obj")
2549         \DWATtype(reference to 11\$)
2550 \end{alltt}
2551 \end{dwflisting}
2552 \caption{C++ template example \#1: DWARF description}
2553 \label{fig:ctemplateexample1dwarf}
2554 \end{figure}
2555
2556 The actual type of the component \texttt{comp} is \texttt{int}, but in the DWARF
2557 the type references the
2558 \DWTAGtemplatetypeparameter{}
2559 for \texttt{T}, which in turn references \texttt{int}. This implies that in the
2560 original template comp was of type \texttt{T} and that was replaced
2561 with \texttt{int} in the instance. 
2562
2563 \needlines{10}
2564 There exist situations where it is
2565 not possible for the DWARF to imply anything about the nature
2566 of the original template. 
2567 Consider the \addtoindex{C++} template source in
2568 Figure \refersec{fig:ctemplateexample2source}
2569 and the DWARF that can describe it in
2570 Figure \refersec{fig:ctemplateexample2dwarf}.
2571
2572 \begin{figure}[!h]
2573 \begin{lstlisting}
2574 // C++ source
2575 //
2576     template<class T>
2577     struct wrapper {
2578         T comp;
2579     };
2580     template<class U>
2581     void consume(wrapper<U> formal)
2582     {
2583         ...
2584     }
2585     wrapper<int> obj;
2586     consume(obj);
2587 \end{lstlisting}
2588 \caption{C++ template example \#2: source}
2589 \label{fig:ctemplateexample2source}
2590 \end{figure}
2591
2592 \begin{figure}[h]
2593 \begin{dwflisting}
2594 \begin{alltt}
2595 ! DWARF description
2596 !
2597 11\$:  \DWTAGstructuretype
2598           \DWATname("wrapper")
2599 12\$:      \DWTAGtemplatetypeparameter
2600               \DWATname("T")
2601               \DWATtype(reference to "int")
2602 13\$:      \DWTAGmember
2603               \DWATname("comp")
2604               \DWATtype(reference to 12\$)
2605 14\$:  \DWTAGvariable
2606           \DWATname("obj")
2607           \DWATtype(reference to 11\$)
2608 21\$:  \DWTAGsubprogram
2609           \DWATname("consume")
2610 22\$:      \DWTAGtemplatetypeparameter
2611               \DWATname("U")
2612               \DWATtype(reference to "int")
2613 23\$:      \DWTAGformalparameter
2614               \DWATname("formal")
2615               \DWATtype(reference to 11\$)
2616 \end{alltt}
2617 \end{dwflisting}
2618 \caption{C++ template example \#2: DWARF description}
2619 \label{fig:ctemplateexample2dwarf}
2620 \end{figure}
2621
2622 In the \DWTAGsubprogram{} 
2623 entry for the instance of consume, \texttt{U} is described as \texttt{int}. 
2624 The type of formal is \texttt{wrapper\textless U\textgreater} in
2625 the source. DWARF only represents instantiations of templates;
2626 there is no entry which represents \texttt{wrapper\textless U\textgreater} 
2627 which is neither
2628 a template parameter nor a template instantiation. The type
2629 of formal is described as \texttt{wrapper\textless int\textgreater},
2630 the instantiation of \texttt{wrapper\textless U\textgreater},
2631 in the \DWATtype{} attribute at 
2632 23\$. 
2633 There is no
2634 description of the relationship between template type parameter
2635 \texttt{T} at 12\$ and \texttt{U} at 22\$ which was used to instantiate
2636 \texttt{wrapper\textless U\textgreater}.
2637
2638 A consequence of this is that the DWARF information would
2639 not distinguish between the existing example and one where
2640 the formal parameter of \texttt{consume} were declared in the source to be
2641 \texttt{wrapper\textless int\textgreater}.
2642
2643
2644 \section{Template Alias Examples}
2645 \label{app:templatealiasexample}
2646
2647 The \addtoindex{C++} template alias shown in
2648 Figure \refersec{fig:ctemplatealiasexample1source}
2649 can be described in DWARF as illustrated 
2650 \addtoindexx{template alias example} in 
2651 Figure \refersec{fig:ctemplatealiasexample1dwarf}.
2652
2653 \begin{figure}[h]
2654 \begin{lstlisting}
2655 // C++ source, template alias example 1
2656 //
2657 template<typename T, typename U>
2658 struct Alpha {
2659     T tango;
2660     U uniform;
2661 };
2662 template<typename V> using Beta = Alpha<V,V>;
2663 Beta<long> b;
2664 \end{lstlisting}
2665 \caption{C++ template alias example \#1: source}
2666 \label{fig:ctemplatealiasexample1source}
2667 \end{figure}
2668
2669 \begin{figure}[h]
2670 \addtoindexx{template alias example 1}
2671 \begin{dwflisting}
2672 \begin{alltt}
2673 ! DWARF representation for variable 'b'
2674 !
2675 20\$:  \DWTAGstructuretype
2676           \DWATname("Alpha")
2677 21\$:      \DWTAGtemplatetypeparameter
2678               \DWATname("T")
2679               \DWATtype(reference to "long")
2680 22\$:      \DWTAGtemplatetypeparameter
2681               \DWATname("U")
2682               \DWATtype(reference to "long")
2683 23\$:      \DWTAGmember
2684               \DWATname("tango")
2685               \DWATtype(reference to 21\$)
2686 24\$:      \DWTAGmember
2687               \DWATname("uniform")
2688               \DWATtype(reference to 22\$)
2689 25\$:  \DWTAGtemplatealias
2690           \DWATname("Beta")
2691           \DWATtype(reference to 20\$)
2692 26\$:      \DWTAGtemplatetypeparameter
2693               \DWATname("V")
2694               \DWATtype(reference to "long")
2695 27\$:  \DWTAGvariable
2696           \DWATname("b")
2697           \DWATtype(reference to 25\$)
2698 \end{alltt}
2699 \end{dwflisting}
2700 \caption{C++ template alias example \#1: DWARF description}
2701 \label{fig:ctemplatealiasexample1dwarf}
2702 \end{figure}
2703
2704 Similarly, the \addtoindex{C++} template alias shown in
2705 Figure \refersec{fig:ctemplatealiasexample2source}
2706 can be described in DWARF as illustrated 
2707 \addtoindexx{template alias example} in 
2708 Figure \refersec{fig:ctemplatealiasexample2dwarf}.
2709
2710 \begin{figure}[h]
2711 \begin{lstlisting}
2712 // C++ source, template alias example 2
2713 //
2714 template<class TX> struct X { };
2715 template<class TY> struct Y { };
2716 template<class T> using Z = Y<T>;
2717 X<Y<int>> y;
2718 X<Z<int>> z;
2719 \end{lstlisting}
2720 \caption{C++ template alias example \#2: source}
2721 \label{fig:ctemplatealiasexample2source}
2722 \end{figure}
2723
2724 \begin{figure}[h]
2725 \addtoindexx{template alias example 2}
2726 \begin{dwflisting}
2727 \begin{alltt}
2728 ! DWARF representation for X<Y<int>>
2729 !
2730 30\$:  \DWTAGstructuretype
2731           \DWATname("Y")
2732 31\$:      \DWTAGtemplatetypeparameter
2733               \DWATname("TY")
2734               \DWATtype(reference to "int")
2735 32\$:  \DWTAGstructuretype
2736           \DWATname("X")
2737 33\$:      \DWTAGtemplatetypeparameter
2738               \DWATname("TX")
2739               \DWATtype(reference to 30\$)
2740 !
2741 ! DWARF representation for X<Z<int>>
2742 !
2743 40\$:  \DWTAGtemplatealias
2744           \DWATname("Z")
2745           \DWATtype(reference to 30\$)
2746 41\$:      \DWTAGtemplatetypeparameter
2747               \DWATname("T")
2748               \DWATtype(reference to "int")
2749 42\$:  \DWTAGstructuretype
2750           \DWATname("X")
2751 43\$:      \DWTAGtemplatetypeparameter
2752               \DWATname("TX")
2753               \DWATtype(reference to 40\$)
2754 !
2755 ! Note that 32\$ and 42\$ are actually the same type
2756 !
2757 50\$:  \DWTAGvariable
2758           \DWATname("y")
2759           \DWATtype(reference to \$32)
2760 51\$:  \DWTAGvariable
2761           \DWATname("z")
2762           \DWATtype(reference to \$42)
2763 \end{alltt}
2764 \end{dwflisting}
2765 \caption{C++ template alias example \#2: DWARF description}
2766 \label{fig:ctemplatealiasexample2dwarf}
2767 \end{figure}
2768
2769 \clearpage
2770 \section{Implicit Pointer Examples}
2771 \label{app:implicitpointerexamples}
2772 If the compiler determines that the value of an object is
2773 constant (either throughout the program, or within a specific
2774 range), it may choose to materialize that constant only when
2775 used, rather than store it in memory or in a register. The
2776 \DWOPimplicitvalue{} operation can be used to describe such a
2777 value. Sometimes, the value may not be constant, but still can be
2778 easily rematerialized when needed. A DWARF expression terminating
2779 in \DWOPstackvalue{} can be used for this case. The compiler may
2780 also eliminate a pointer value where the target of the pointer
2781 resides in memory, and the \DWOPstackvalue{} operator may be used
2782 to rematerialize that pointer value. In other cases, the compiler
2783 will eliminate a pointer to an object that itself needs to be
2784 materialized. Since the location of such an object cannot be
2785 represented as a memory address, a DWARF expression cannot give
2786 either the location or the actual value or a pointer variable
2787 that would refer to that object. The \DWOPimplicitpointer{}
2788 operation can be used to describe the pointer, and the debugging
2789 information entry to which its first operand refers describes the
2790 value of the dereferenced object. A DWARF consumer will not be
2791 able to show the location or the value of the pointer variable,
2792 but it will be able to show the value of the dereferenced
2793 pointer.
2794
2795 Consider the \addtoindex{C} source shown in 
2796 Figure \refersec{fig:cimplicitpointerexample1source}.
2797 Assume that the function \texttt{foo} is not inlined,
2798 that the argument x is passed in register 5, and that the
2799 function \texttt{foo} is optimized by the compiler into just 
2800 an increment of the volatile variable \texttt{v}. Given these
2801 assumptions a possible DWARF description is shown in
2802 Figure \refersec{fig:cimplicitpointerexample1dwarf}.
2803
2804 \begin{figure}[h]
2805 \begin{lstlisting}
2806 struct S { short a; char b, c; };
2807 volatile int v;
2808 void foo (int x)
2809 {
2810     struct S s = { x, x + 2, x + 3 };
2811     char *p = &s.b;
2812     s.a++;
2813     v++;
2814 }
2815 int main ()
2816 {
2817     foo (v+1);
2818     return 0;
2819 }
2820 \end{lstlisting}
2821 \caption{C implicit pointer example \#1: source}
2822 \label{fig:cimplicitpointerexample1source}
2823 \end{figure}
2824
2825 \begin{figure}[h]
2826 \addtoindexx{implicit pointer example}
2827 \begin{dwflisting}
2828 \begin{alltt}
2829 1\$: \DWTAGstructuretype
2830         \DWATname("S")
2831         \DWATbytesize(4)
2832 10\$:    \DWTAGmember
2833             \DWATname("a")
2834             \DWATtype(reference to "short int")
2835             \DWATdatamemberlocation(constant 0)
2836 11\$:    \DWTAGmember
2837             \DWATname("b")
2838             \DWATtype(reference to "char")
2839             \DWATdatamemberlocation(constant 2)
2840 12\$:    \DWTAGmember
2841             \DWATname("c")
2842             \DWATtype(reference to "char")
2843             \DWATdatamemberlocation(constant 3)
2844 2\$: \DWTAGsubprogram
2845         \DWATname("foo")
2846 20\$:    \DWTAGformalparameter
2847             \DWATname("x")
2848             \DWATtype(reference to "int")
2849             \DWATlocation(\DWOPregfive)
2850 21\$:    \DWTAGvariable
2851             \DWATname("s")
2852             \DWATlocation(expression=
2853                 \DWOPbregfive(1) \DWOPstackvalue \DWOPpiece(2)
2854                 \DWOPbregfive(2) \DWOPstackvalue \DWOPpiece(1)
2855                 \DWOPbregfive(3) \DWOPstackvalue \DWOPpiece(1))
2856 22\$:    \DWTAGvariable
2857             \DWATname("p")
2858             \DWATtype(reference to "char *")
2859             \DWATlocation(expression=
2860                 \DWOPimplicitpointer(reference to 21\$, 2))
2861 \end{alltt}
2862 \end{dwflisting}
2863 \caption{C implicit pointer example \#1: DWARF description}
2864 \label{fig:cimplicitpointerexample1dwarf}
2865 \end{figure}
2866
2867 In Figure \refersec{fig:cimplicitpointerexample1dwarf},
2868 even though variables \texttt{s} and \texttt{p} are both optimized 
2869 away completely, this DWARF description still allows a debugger to 
2870 print the value of the variable \texttt{s}, namely \texttt{(2, 3, 4)}. 
2871 Similarly, because the variable \texttt{s} does not live in
2872 memory, there is nothing to print for the value of \texttt{p}, but the 
2873 debugger should still be able to show that \texttt{p[0]} is 3, 
2874 \texttt{p[1]} is 4, \texttt{p[-1]} is 0 and \texttt{p[-2]} is 2.
2875
2876 \needlines{6}
2877 As a further example, consider the C source 
2878 shown in Figure \refersec{fig:cimplicitpointerexample2source}. Make
2879 the following assumptions about how the code is compiled:
2880 \begin{itemize}
2881 \item The function \texttt{foo} is inlined
2882 into function \texttt{main}
2883 \item The body of the main function is optimized to just
2884 three blocks of instructions which each increment the volatile
2885 variable \texttt{v}, followed by a block of instructions to return 0 from
2886 the function
2887 \item Label \texttt{label0} is at the start of the main
2888 function, \texttt{label1} follows the first \texttt{v++} block, 
2889 \texttt{label2} follows the second \texttt{v++} block and 
2890 \texttt{label3} is at the end of the main function
2891 \item Variable \texttt{b} is optimized away completely, as it isn't used
2892 \item The string literal \texttt{"opq"} is optimized away as well
2893 \end{itemize}
2894 Given these assumptions a possible DWARF description is shown in
2895 Figure \refersec{fig:cimplicitpointerexample2dwarf}.
2896
2897 \begin{figure}[h]
2898 \begin{lstlisting}
2899 static const char *b = "opq";
2900 volatile int v;
2901 static inline void foo (int *p)
2902 {
2903     (*p)++;
2904     v++;
2905     p++;
2906     (*p)++;
2907     v++;
2908 }
2909 int main ()
2910 {
2911     int a[2] = { 1, 2 };
2912     v++;
2913     foo (a);
2914     return a[0] + a[1] - 5;
2915 }
2916 \end{lstlisting}
2917 \caption{C implicit pointer example \#2: source}
2918 \label{fig:cimplicitpointerexample2source}
2919 \end{figure}
2920
2921 \begin{figure}[h]
2922 \addtoindexx{implicit pointer example}
2923 \begin{dwflisting}
2924 \begin{alltt}
2925 1\$: \DWTAGvariable
2926         \DWATname("b")
2927         \DWATtype(reference to "const char *")
2928         \DWATlocation(expression=
2929             \DWOPimplicitpointer(reference to 2$, 0))
2930 2\$: \DWTAGdwarfprocedure
2931         \DWATlocation(expression=
2932             \DWOPimplicitvalue(4, \{'o', 'p', 'q', '\slash0'\}))
2933 3\$: \DWTAGsubprogram
2934         \DWATname("foo")
2935         \DWATinline(\DWINLdeclaredinlined)
2936 30\$:    \DWTAGformalparameter
2937             \DWATname("p")
2938             \DWATtype(reference to "int *")
2939 4\$: \DWTAGsubprogram
2940         \DWATname("main")
2941 40\$:           \DWTAGvariable
2942             \DWATname("a")
2943             \DWATtype(reference to "int[2]")
2944             \DWATlocation(location list 98$)
2945 41\$:    \DWTAGinlinedsubroutine
2946             \DWATabstractorigin(reference to 3$)
2947 42\$:        \DWTAGformalparameter
2948                 \DWATabstractorigin(reference to 30$)
2949                 \DWATlocation(location list 99$)
2950
2951 ! .debug_loc section
2952 98\$:<label0 in main> .. <label1 in main>
2953         \DWOPlitone \DWOPstackvalue \DWOPpiece(4)
2954         \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
2955     <label1 in main> .. <label2 in main>
2956         \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
2957         \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
2958     <label2 in main> .. <label3 in main>
2959         \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
2960         \DWOPlitthree \DWOPstackvalue \DWOPpiece(4)
2961     0 .. 0
2962 99\$:<label1 in main> .. <label2 in main>
2963         \DWOPimplicitpointer(reference to 40\$, 0)
2964     <label2 in main> .. <label3 in main>
2965         \DWOPimplicitpointer(reference to 40\$, 4)
2966     0 .. 0
2967 \end{alltt}
2968 \end{dwflisting}
2969 \caption{C implicit pointer example \#2: DWARF description}
2970 \label{fig:cimplicitpointerexample2dwarf}
2971 \end{figure}
2972
2973 \clearpage
2974 \section{String Type Examples}
2975 \label{app:stringtypeexamples}
2976 Consider the \addtoindex{Fortran 2003} string type example source in
2977 Figure \referfol{fig:stringtypeexamplesource}. The DWARF representation in
2978 Figure \refersec{fig:stringtypeexampledwarf} is appropriate.
2979
2980 \begin{figure}[h]
2981 \begin{lstlisting}
2982         program character_kind
2983             use iso_fortran_env
2984             implicit none
2985             integer, parameter :: ascii = 
2986                 selected_char_kind ("ascii")
2987             integer, parameter :: ucs4  = 
2988                 selected_char_kind ('ISO_10646')
2989 \addtoindexx{ISO 10646 character set standard}             
2990             character(kind=ascii, len=26) :: alphabet
2991             character(kind=ucs4,  len=30) :: hello_world
2992             character (len=*), parameter :: all_digits="0123456789"
2993               
2994             alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
2995             hello_world = ucs4_'Hello World and Ni Hao -- ' &
2996                           // char (int (z'4F60'), ucs4)     &
2997                           // char (int (z'597D'), ucs4)
2998               
2999             write (*,*) alphabet
3000             write (*,*) all_digits
3001               
3002             open (output_unit, encoding='UTF-8')
3003             write (*,*) trim (hello_world)
3004         end program character_kind
3005 \end{lstlisting}
3006 \caption{String type example: source}
3007 \label{fig:stringtypeexamplesource}
3008 \end{figure}
3009
3010 \begin{figure}[h]
3011 \begin{dwflisting}
3012 \begin{alltt}
3013
3014 1\$: \DWTAGbasetype
3015         \DWATencoding (\DWATEASCII)
3016
3017 2\$: \DWTAGbasetype
3018         \DWATencoding (\DWATEUCS)
3019         \DWATbytesize (4)
3020
3021 3\$: \DWTAGstringtype
3022         \DWATbytesize (10)
3023
3024 4\$: \DWTAGconsttype
3025         \DWATtype (reference to 3\$)
3026       
3027 5\$: \DWTAGstringtype
3028         \DWATtype (1\$)
3029         \DWATstringlength ( ... )
3030         \DWATstringlengthbytesize ( ... )
3031         \DWATdatalocation ( ... )
3032       
3033 6\$: \DWTAGstringtype
3034         \DWATtype (2\$)
3035         \DWATstringlength ( ... )
3036         \DWATstringlengthbytesize ( ... )
3037         \DWATdatalocation ( ... )
3038
3039 7\$: \DWTAGvariable
3040         \DWATname (alphabet)
3041         \DWATtype (5\$)
3042         \DWATlocation ( ... )
3043
3044 8\$: \DWTAGconstant
3045         \DWATname (all\_digits)
3046         \DWATtype (4\$)
3047         \DWATconstvalue ( ... )
3048
3049 9\$: \DWTAGvariable
3050         \DWATname (hello\_world)
3051         \DWATtype (6\$)
3052         \DWATlocation ( ... )
3053         
3054 \end{alltt}
3055 \end{dwflisting}
3056 \caption{String type example: DWARF representation}
3057 \label{fig:stringtypeexampledwarf}
3058 \end{figure}
3059
3060 \clearpage
3061 \section{Call Site Examples}
3062 \label{app:callsiteexamples}
3063 The following examples use a hypothetical machine which: 
3064 \begin{itemize}
3065 \item
3066 Passes the first argument in register 0, the second in register 1, and the third in register 2.
3067 \item
3068 Keeps the stack pointer is register 3.
3069 \item
3070 Has one call preserved register 4.
3071 \item
3072 Returns a function value in register 0.
3073 \end{itemize}
3074
3075 \subsection{Call Site Example \#1 (C)}
3076 Consider the \addtoindex{C} source in Figure \referfol{fig:callsiteexample1source}.
3077
3078 \begin{figure}[h]
3079 \begin{lstlisting}
3080
3081 extern void fn1 (long int, long int, long int);
3082
3083 long int
3084 fn2 (long int a, long int b, long int c) 
3085 {
3086     long int q = 2 * a;
3087     fn1 (5, 6, 7); 
3088     return 0;
3089 }
3090  
3091 long int
3092 fn3 (long int x, long int (*fn4) (long int *))
3093 {
3094     long int v, w, w2, z;
3095     w = (*fn4) (&w2);
3096     v = (*fn4) (&w2);
3097     z = fn2 (1, v + 1, w);
3098     {
3099         int v1 = v + 4;
3100         z += fn2 (w, v * 2, x);
3101     }
3102     return z;
3103 }
3104 \end{lstlisting}
3105 \caption{Call Site Example \#1: Source}
3106 \label{fig:callsiteexample1source}
3107 \end{figure}
3108
3109 Possible generated code for this source is shown using a suggestive 
3110 pseudo-\linebreak[0]assembly notation in Figure \refersec{fig:callsiteexample1code}.
3111
3112 \begin{figure}[ht]
3113 \begin{lstlisting}
3114 fn2:
3115 L1:
3116     %reg2 = 7   ! Load the 3rd argument to fn1
3117     %reg1 = 6   ! Load the 2nd argument to fn1
3118     %reg0 = 5   ! Load the 1st argument to fn1
3119 L2:
3120     call fn1
3121     %reg0 = 0   ! Load the return value from the function
3122     return
3123 L3:
3124 fn3:
3125     ! Decrease stack pointer to reserve local stack frame
3126     %reg3 = %reg3 - 32
3127     [%reg3] = %reg4       ! Save the call preserved register to
3128                           !   stack
3129     [%reg3 + 8] = %reg0   ! Preserve the x argument value
3130     [%reg3 + 16] = %reg1  ! Preserve the fn4 argument value
3131     %reg0 = %reg3 + 24    ! Load address of w2 as argument
3132     call %reg1            ! Call fn4 (indirect call)
3133 L6:
3134     %reg2 = [%reg3 + 16]  ! Load the fn4 argument value
3135     [%reg3 + 16] = %reg0  ! Save the result of the first call (w)
3136     %reg0 = %reg3 + 24    ! Load address of w2 as argument
3137     call %reg2            ! Call fn4 (indirect call)
3138 L7:
3139     %reg4 = %reg0         ! Save the result of the second call (v) 
3140                           !   into register.
3141     %reg2 = [%reg3 + 16]  ! Load 3rd argument to fn2 (w)
3142     %reg1 = %reg4 + 1     ! Compute 2nd argument to fn2 (v + 1)
3143     %reg0 = 1             ! Load 1st argument to fn2
3144     call fn2
3145 L4:
3146     %reg2 = [%reg3 + 8]   ! Load the 3rd argument to fn2 (x)
3147     [%reg3 + 8] = %reg0   ! Save the result of the 3rd call (z)
3148     %reg0 = [%reg3 + 16]  ! Load the 1st argument to fn2 (w)
3149     %reg1 = %reg4 + %reg4 ! Compute the 2nd argument to fn2 (v * 2)
3150     call fn2
3151 L5:
3152     %reg2 = [%reg3 + 8]   ! Load the value of z from the stack
3153     %reg0 = %reg0 + %reg2 ! Add result from the 4th call to it
3154 L8:
3155     %reg4 = [%reg3]       ! Restore original value of call preserved 
3156                           !   register
3157     %reg3 = %reg3 + 32    ! Leave stack frame
3158     return
3159 \end{lstlisting}
3160 \caption{Call Site Example \#1: Code}
3161 \label{fig:callsiteexample1code}
3162 \end{figure}
3163
3164 \clearpage
3165 The location list for variable \texttt{a} in function \texttt{fn2}
3166 might look like:
3167 %\begin{figure}[h]
3168 \begin{lstlisting}
3169
3170 ! Before the call to fn1 the argument a is live in the register 0
3171 !
3172 <L1, L2> DW_OP_reg0
3173
3174 ! Afterwards it is not, the call could have clobbered the register,
3175 ! and it is not saved in the fn2 function stack frame either, but 
3176 ! perhap scan be looked up in the caller
3177 !
3178 <L2, L3> DW_OP_entry_value 1 DW_OP_reg0 DW_OP_stack_value
3179 <0, 0>
3180
3181 \end{lstlisting}
3182 %\end{figure}
3183 (where the notation \doublequote{\texttt{<m, n>}} specifies the address
3184 range over which the following location description applies).
3185
3186 Similarly, the variable q in fn2 then might have location list:
3187 \begin{lstlisting}
3188
3189 ! Before the call to fn1 the value of q can be computed as two times
3190 ! the value of register 0
3191 !
3192 <L1, L2> DW_OP_lit2 DW_OP_breg0 0 DW_OP_mul DW_OP_stack_value
3193
3194 ! Afterwards it can be computed from the original value of the first
3195 ! parameter, multiplied by two
3196 !
3197 <L2, L3> DW_OP_lit2 DW_OP_entry_value 1 DW_OP_reg0 DW_OP_mul DW_OP_stack_value
3198 <0, 0>
3199
3200 \end{lstlisting}
3201
3202 Variables \texttt{b} and \texttt{c} each have a location list similar to 
3203 that for variable \texttt{a},
3204 except for a different label between the two ranges and they
3205 use \DWOPregone{} and \DWOPregtwo{}, respectively, instead of \DWOPregzero.
3206
3207
3208 The call sites for all the calls in function \texttt{fn3} are children of the
3209 \DWTAGsubprogram{} entry for \texttt{fn3} (or of its \DWTAGlexicalblock{} entry
3210 if there is any for the whole function). 
3211 This is shown in Figure \refersec{fig:callsiteexample1dwarf}.
3212
3213 \begin{figure}[h]
3214 \figurepart{1}{2}
3215 \begin{dwflisting}
3216 \begin{alltt}
3217     \DWTAGcallsite
3218         \DWATcallreturnpc(L6) ! First indirect call to (*fn4) in fn3.
3219         ! The address of the call is preserved across the call in memory at
3220         ! stack pointer + 16 bytes.
3221         \DWATcalltarget(\DWOPbregthree{} 16 \DWOPderef)
3222         \DWTAGcallsiteparameter
3223             \DWATlocation(\DWOPregzero)
3224             ! Value of the first parameter is equal to stack pointer + 24 bytes.
3225             \DWATcallvalue(\DWOPbregthree{} 24)
3226     \DWTAGcallsite
3227         \DWATcallreturnpc(L7) ! Second indirect call to (*fn4) in fn3.
3228         ! The address of the call is not preserved across the call anywhere, but
3229         ! could be perhaps looked up in fn3's caller.
3230         \DWATcalltarget(\DWOPentryvalue{} 1 \DWOPregone)
3231         \DWTAGcallsiteparameter
3232             \DWATlocation(\DWOPregzero)
3233             \DWATcallvalue(\DWOPbregthree{} 24)
3234     \DWTAGcallsite
3235         \DWATcallreturnpc(L4) ! 3rd call in fn3, direct call to fn2
3236         \DWATcallorigin(reference to fn2 DW_TAG_subprogram)
3237         \DWTAGcallsiteparameter
3238             \DWATcallparameter(reference to formal parameter a in subprogram fn2)
3239             \DWATlocation(\DWOPregzero)
3240             ! First parameter to fn2 is constant 1
3241             \DWATcallvalue(\DWOPlitone)
3242         \DWTAGcallsiteparameter
3243             \DWATcallparameter(reference to formal parameter b in subprogram fn2)
3244             \DWATlocation(\DWOPregone)
3245             ! Second parameter to fn2 can be computed as the value of the call
3246             !   preserved register 4 in the fn3 function plus one
3247             \DWATcallvalue(\DWOPbregfour{} 1)
3248         \DWTAGcallsiteparameter
3249             \DWATcallparameter(reference to formal parameter c in subprogram fn2)
3250             \DWATlocation(\DWOPregtwo)
3251             ! Third parameter's value is preserved in memory at fn3's stack pointer
3252             !   plus 16 bytes
3253             \DWATcallvalue(\DWOPbregthree{} 16 \DWOPderef)
3254 \end{alltt}
3255 \end{dwflisting}
3256 \caption{Call Site Example \#1: DWARF Encoding}
3257 \label{fig:callsiteexample1dwarf}
3258 \end{figure}
3259
3260 \begin{figure}
3261 \figurepart{2}{2}
3262 \begin{dwflisting}
3263 \begin{alltt}
3264 \DWTAGlexicalblock
3265     \DWATlowpc(L4)
3266     \DWAThighpc(L8)
3267     \DWTAGvariable
3268         \DWATname("v1")
3269         \DWATtype(reference to int)
3270         ! Value of the v1 variable can be computed as value of register 4 plus 4
3271         \DWATlocation(\DWOPbregfour{} 4 \DWOPstackvalue)
3272     \DWTAGcallsite
3273         \DWATcallreturnpc(L5) ! 4th call in fn3, direct call to fn2
3274         \DWATcalltarget(reference to subprogram fn2)
3275         \DWTAGcallsiteparameter
3276             \DWATcallparameter(reference to formal parameter a in subprogram fn2)
3277             \DWATlocation(\DWOPregzero)
3278             ! Value of the 1st argument is preserved in memory at fn3's stack 
3279             !   pointer + 16 bytes.
3280             \DWATcallvalue(\DWOPbregthree{} 16 \DWOPderef)
3281         \DWTAGcallsiteparameter
3282             \DWATcallparameter(reference to formal parameter b in subprogram fn2)
3283             \DWATlocation(\DWOPregone)
3284             ! Value of the 2nd argument can be computed using the preserved 
3285             !   register 4 multiplied by 2
3286             \DWATcallvalue(\DWOPlittwo{} \DWOPregfour{} 0 \DWOPmul)
3287         \DWTAGcallsiteparameter
3288             \DWATcallparameter(reference to formal parameter c in subprogram fn2)
3289             \DWATlocation(\DWOPregtwo)
3290             ! Value of the 3rd argument is not preserved, but could be perhaps 
3291             ! computed from the value passed fn3's caller.
3292             \DWATcallvalue(\DWOPentryvalue{} 1 \DWOPregzero)
3293 \end{alltt}
3294 \end{dwflisting}
3295 \begin{center}
3296 \vspace{3mm}
3297 Figure~\ref{fig:callsiteexample1dwarf} Call Site Example \#1: DWARF Encoding \textit{(concluded)}
3298 \end{center}
3299 \end{figure}
3300
3301 \clearpage
3302 \subsection{Call Site Example \#2 (Fortran)}
3303 Consider the \addtoindex{Fortran} source in 
3304 Figure \refersec{fig:callsiteexample2source}
3305 which is used to illustrate how Fortran's \doublequote{pass by reference}
3306 parameters can be handled.
3307
3308 \begin{figure}[h]
3309 \begin{lstlisting}
3310 subroutine fn4 (n)
3311     integer :: n, x
3312     x = n
3313     n = n / 2
3314     call fn6
3315 end subroutine
3316 subroutine fn5 (n)
3317     interface fn4
3318         subroutine fn4 (n)
3319             integer :: n
3320         end subroutine
3321     end interface fn4
3322     integer :: n, x
3323     call fn4 (n)
3324     x = 5
3325     call fn4 (x)
3326 end subroutine fn5
3327 \end{lstlisting}
3328 \caption{Call Site Example \#2: Source}
3329 \label{fig:callsiteexample2source}
3330 \end{figure}
3331
3332 Possible generated code for this source is shown using a suggestive 
3333 pseudo-\linebreak[0]assembly notation in Figure \refersec{fig:callsiteexample2code}.
3334 \begin{figure}[h]
3335 \begin{lstlisting}
3336
3337 fn4:
3338     %reg2 = [%reg0]   ! Load value of n (passed by reference)
3339     %reg2 = %reg2 / 2 ! Divide by 2
3340     [%reg0] = %reg2   ! Update value of n
3341     call fn6          ! Call some other function
3342     return
3343
3344 fn5:
3345     %reg3 = %reg3 - 8 ! Decrease stack pointer to create stack frame
3346     call fn4          ! Call fn4 with the same argument by reference 
3347                       !   as fn5 has been called with
3348 L9:
3349     [%reg3] = 5       ! Pass value of 5 by reference to fn4
3350     %reg0 = %reg3     ! Put address of the value 5 on the stack
3351                       !   into 1st argument register
3352     call fn4
3353 L10:
3354     %reg3 = %reg3 + 8 ! Leave stack frame
3355     return
3356     
3357 \end{lstlisting}
3358 \caption{Call Site Example \#2: Code}
3359 \label{fig:callsiteexample2code}
3360 \end{figure}
3361
3362 The location description for variable \texttt{x} in function 
3363 \texttt{f}n4 might be:
3364 \begin{lstlisting}
3365 DW_OP_entry_value 4 DW_OP_breg0 0 DW_OP_deref_size 4 DW_OP_stack_value
3366 \end{lstlisting}
3367
3368 The call sites in (just) function \texttt{fn5} might be as shown in 
3369 Figure \refersec{fig:callsiteexample2dwarf}.
3370
3371 \begin{figure}[h]
3372 \begin{dwflisting}
3373 \begin{alltt}
3374
3375 \DWTAGcallsite
3376     \DWATcallreturnpc(L9) ! First call to fn4
3377     \DWATcallorigin(reference to subprogram fn4)
3378     \DWTAGcallsiteparameter
3379         \DWATcallparameter(reference to formal parameter n in subprogram fn4)
3380         \DWATlocation(\DWOPregzero)
3381         ! The value of register 0 at the time of the call can be perhaps 
3382         !   looked up in fn5's caller
3383         \DWATcallvalue(\DWOPentryvalue{} 1 \DWOPregzero)
3384         ! DW_AT_call_data_location(DW_OP_push_object_address) ! left out, implicit
3385         ! And the actual value of the parameter can be also perhaps looked up in
3386         ! fn5's caller
3387         \DWATcalldatavalue(\DWOPentryvalue{} 4 \DWOPbregzero{} 0 \DWOPderefsize 4)
3388         
3389 \DWTAGcallsite
3390     \DWATcallreturnpc(L10) ! Second call to fn4
3391     \DWATcallorigin(reference to subprogram fn4)
3392     \DWTAGcallsiteparameter
3393         \DWATcallparameter(reference to formal parameter n in subprogram fn4)
3394         \DWATlocation(\DWOPregzero)
3395         ! The value of register 0 at the time of the call is equal to the stack
3396         ! pointer value in fn5
3397         \DWATcallvalue(\DWOPbregthree{} 0)
3398         ! DW_AT_call_data_location(DW_OP_push_object_address) ! left out, implicit
3399         ! And the value passed by reference is constant 5
3400         \DWATcalldatavalue(\DWOPlitfive)
3401         
3402 \end{alltt}
3403 \end{dwflisting}
3404 \caption{Call Site Example \#2: DWARF Encoding}
3405 \label{fig:callsiteexample2dwarf}
3406 \end{figure}