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