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