2ded5e88a0d7e6cfd46818a7612bb3e790e40079
[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{General Description Examples}
9 \label{app:generaldescriptionexamples}
10
11
12 \subsection{Compilation Units and Abbreviations Table Example}
13 \label{app:compilationunitsandabbreviationstableexample}
14
15 Figure \refersec{fig:compilationunitsandabbreviationstable}
16 depicts the relationship of the abbreviations tables contained
17 \addtoindexx{abbreviations table!example}
18 \addtoindexx{\texttt{.debug\_abbrev}!example}
19 \addtoindexx{\texttt{.debug\_info}!example}
20 in the \dotdebugabbrev{}
21 section to the information contained in
22 the \dotdebuginfo{}
23 section. Values are given in symbolic form,
24 where possible.
25
26 The figure corresponds to the following two trivial source files:
27
28 File myfile.c
29 \begin{lstlisting}[numbers=none]
30 typedef char* POINTER;
31 \end{lstlisting}
32 File myfile2.c
33 \begin{lstlisting}[numbers=none]
34 typedef char* strp;
35 \end{lstlisting}
36
37 % Ensures we get the following float out before we go on.
38 \clearpage
39 \begin{figure}[h]
40 %\centering
41 %\setlength{\linewidth}{1.1\linewidth}
42 \begin{minipage}[t]{0.03\linewidth}
43 \flushright
44 \scriptsize
45 % Note: alltt is used to step down the needed number of lines to the labels
46 \begin{alltt}
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67 \textit{e1:}
68
69
70
71
72 \textit{e2:}
73 \end{alltt}
74 \end{minipage}
75 %
76 \begin{minipage}[t]{0.38\linewidth}
77 \centering
78 Compilation Unit \#1: \dotdebuginfo{}
79 \begin{framed}
80 \scriptsize
81 \begin{alltt}
82 \textit{length}
83 4
84 \textit{a1 (abbreviations table offset)}
85 4
86 \vspace{0.01cm}
87 \hrule
88 1
89 "myfile.c"
90 "Best Compiler Corp, V1.3"
91 "/home/mydir/src"
92 \DWLANGCeightynine
93 0x0
94 0x55
95 \DWFORMsecoffset
96 0x0
97 \vspace{0.01cm}
98 \hrule
99 2
100 "char"
101 \DWATEunsignedchar
102 1
103 \vspace{0.01cm}
104 \hrule
105 3
106 \textit{e1  (debug info offset)}
107 \vspace{0.01cm}
108 \hrule
109 4
110 "POINTER"
111 \textit{e2  (debug info offset)}
112 \vspace{0.01cm}
113 \hrule
114 0
115 \end{alltt}
116 %
117 %
118 \end{framed}
119 Compilation Unit \#2: \dotdebuginfo{}
120 \begin{framed}
121 \scriptsize
122 \begin{alltt}
123 \textit{length}
124 4
125 \textit{a1 (abbreviations table offset)}
126 4
127 \vspace{0.01cm}
128 \hrule
129 ...
130 \vspace{0.01cm}
131 \hrule
132 4
133 "strp"
134 \textit{e2  (debug info offset)}
135 \vspace{0.01cm}
136 \hrule
137 ...
138 \end{alltt}
139 %
140 %
141 \end{framed}
142 \end{minipage}
143 \hfill 
144 % Place the label for the abbreviation table
145 \begin{minipage}[t]{0.03\linewidth}
146 \flushright
147 \scriptsize
148 % Note: alltt is used to step down the needed number of lines to the label
149 \begin{alltt}
150
151
152
153
154
155 \textit{a1:}
156 \end{alltt}
157 \end{minipage}
158 %
159 \begin{minipage}[t]{0.41\linewidth}
160 \centering
161 Abbreviation Table: \dotdebugabbrev{}
162 \begin{framed}
163 \scriptsize
164 \begin{alltt}\vspace{0.06cm}
165 1
166 \DWTAGcompileunit
167 \DWCHILDRENyes
168 \DWATname       \DWFORMstring
169 \DWATproducer   \DWFORMstring
170 \DWATcompdir   \DWFORMstring
171 \DWATlanguage   \DWFORMdataone
172 \DWATlowpc     \DWFORMaddr
173 \DWAThighpc    \DWFORMdataone
174 \DWATstmtlist  \DWFORMindirect
175 0
176 \vspace{0.01cm}
177 \hrule
178 2
179 \DWTAGbasetype
180 \DWCHILDRENno
181 \DWATname       \DWFORMstring
182 \DWATencoding   \DWFORMdataone
183 \DWATbytesize  \DWFORMdataone
184 0
185 \vspace{0.01cm}
186 \hrule
187 3
188 \DWTAGpointertype
189 \DWCHILDRENno
190 \DWATtype       \DWFORMreffour
191 0
192 \vspace{0.01cm}
193 \hrule
194 4
195 \DWTAGtypedef
196 \DWCHILDRENno
197 \DWATname      \DWFORMstring
198 \DWATtype      \DWFORMrefaddr
199 0
200 \vspace{0.01cm}
201 \hrule
202 0
203 \end{alltt}
204 \end{framed}
205 \end{minipage}
206
207 \vspace{0.2cm}
208 \caption{Compilation units and abbreviations table} \label{fig:compilationunitsandabbreviationstable}
209 \end{figure}
210
211 % Ensures we get the above float out before we go on.
212 \clearpage
213
214 \subsection{DWARF Stack Operation Examples}
215 \label{app:dwarfstackoperationexamples}
216 \textit {The 
217 \addtoindexx{DWARF expression!examples}
218 stack operations defined in 
219 Section \refersec{chap:stackoperations}.
220 are fairly conventional, but the following
221 examples illustrate their behavior graphically.}
222
223 \begin{longtable}[c]{rrcrr} 
224 \multicolumn{2}{c}{Before} & Operation & \multicolumn{2}{c}{After} \\
225 \hline
226 \endhead
227 \endfoot
228 0& 17& \DWOPdup{} &0 &17 \\*
229 1&   29& &  1 & 17 \\*
230 2& 1000 & & 2 & 29\\*
231 & & &         3&1000\\
232
233 & & & & \\
234 0 & 17 & \DWOPdrop{} & 0 & 29 \\*
235 1 &29  &            & 1 & 1000 \\*
236 2 &1000& & &          \\
237
238 & & & & \\
239 0 & 17 & \DWOPpick, 2 & 0 & 1000 \\*
240 1 & 29 & & 1&17 \\*
241 2 &1000& &2&29 \\*
242   &    & &3&1000 \\
243
244 & & & & \\
245 0&17& \DWOPover&0&29 \\*
246 1&29& &  1&17 \\*
247 2&1000 & & 2&29\\*
248  &     & & 3&1000 \\
249
250 & & & & \\
251 0&17& \DWOPswap{} &0&29 \\*
252 1&29& &  1&17 \\*
253 2&1000 & & 2&1000 \\
254
255 & & & & \\
256 0&17&\DWOProt{} & 0 &29 \\*
257 1&29 & & 1 & 1000 \\*
258 2& 1000 & &  2 & 17 \\
259 \end{longtable}
260
261 \subsection{DWARF Location Description Examples}
262 \label{app:dwarflocationdescriptionexamples}
263
264 Following are examples of DWARF operations used to form location descriptions:
265
266 \newcommand{\descriptionitemnl}[1]
267         {\vspace{0.5\baselineskip}\item[#1]\mbox{}\\\vspace{0.5\baselineskip}}
268 \begin{description}
269 \descriptionitemnl{\DWOPregthree}
270 The value is in register 3.
271
272 \descriptionitemnl{\DWOPregx{} 54}
273 The value is in register 54.
274
275 \descriptionitemnl{\DWOPaddr{} 0x80d0045c}
276 The value of a static variable is at machine address 0x80d0045c.
277
278 \descriptionitemnl{\DWOPbregeleven{} 44}
279 Add 44 to the value in register 11 to get the address of an automatic
280 variable instance.
281
282 \needlines{4}
283 \descriptionitemnl{\DWOPfbreg{} -50}
284 Given a \DWATframebase{} value of
285 \doublequote{\DWOPbregthirtyone{} 64,} this example
286 computes the address of a local variable that is -50 bytes from a
287 logical frame pointer that is computed by adding 64 to the current
288 stack pointer (register 31).
289
290 \descriptionitemnl{\DWOPbregx{} 54 32 \DWOPderef}
291 A call-by-reference parameter whose address is in the word 32 bytes
292 from where register 54 points.
293
294 \descriptionitemnl{\DWOPplusuconst{} 4}
295 A structure member is four bytes from the start of the structure
296 instance. The base address is assumed to be already on the stack.
297
298 \descriptionitemnl{\DWOPregthree{} \DWOPpiece{} 4 \DWOPregten{} \DWOPpiece{} 2}
299 A variable whose first four bytes reside in register 3 and whose next
300 two bytes reside in register 10.
301
302 \needlines{4}
303 \descriptionitemnl{\DWOPregzero{} \DWOPpiece{} 4 \DWOPpiece{} 4 \DWOPfbreg{} -12 \DWOPpiece{} 4}
304 \vspace{-2\parsep}A twelve byte value whose first four bytes reside in register zero,
305 whose middle four bytes are unavailable (perhaps due to optimization),
306 and whose last four bytes are in memory, 12 bytes before the frame
307 base.
308
309 \descriptionitemnl{\DWOPbregone{} 0 \DWOPbregtwo{} 0 \DWOPplus{} \DWOPstackvalue{} }
310 Add the contents of r1 and r2 to compute a value. This value is the
311 \doublequote{contents} of an otherwise anonymous location.
312
313 \needlines{4}
314 \descriptionitemnl{\DWOPlitone{} \DWOPstackvalue{} \DWOPpiece{} 4 \DWOPbregthree{} 0 \DWOPbregfour{} 0}
315 \vspace{-3\parsep}\descriptionitemnl{
316 \hspace{0.5cm}\DWOPplus{} \DWOPstackvalue{} \DWOPpiece{} 4 }
317 The object value is found in an anonymous (virtual) location whose
318 value consists of two parts, given in memory address order: the 4 byte
319 value 1 followed by the four byte value computed from the sum of the
320 contents of r3 and r4.
321
322 \descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregone{} \DWOPstackvalue }
323 The value register 1 had upon entering the current subprogram.
324
325 \descriptionitemnl{\DWOPentryvalue{} 2 \DWOPbregone{} 0 \DWOPstackvalue }
326 The value register 1 had upon entering the current subprogram (same as the previous example).
327 %Both of these location descriptions evaluate to the value register 1 had upon
328 %entering the current subprogram.
329
330 %FIXME: The following gets an undefined control sequence error for reasons unknown... 
331 %\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregthirtyone{} \DWOPregone{} \DWOPadd{} \DWOPstackvalue }
332 %The value register 31 had upon entering the current subprogram
333 %plus the value register 1 currently has.
334
335 \descriptionitemnl{\DWOPentryvalue{} 3 \DWOPbregfour{} 16 \DWOPderef{} \DWOPstackvalue }
336 %FIXME: similar undefined as just above
337 %\descriptionitemnl{\DWOPentryvalue{} 6 \DWOPentryvalue{} 1 \DWOPregfour{} \DWOPplusuconst{} 16 \DWOPderef{} \DWOPstackvalue }
338 %These two location expressions do the same thing, p
339 Add 16 to the value register 4 had upon entering the current subprogram
340 to form an address and then push the value of the memory location at that address.
341
342 \end{description}
343
344 \clearpage
345 \section{Aggregate Examples}
346 \label{app:aggregateexamples}
347
348 The following examples illustrate how to represent some of
349 the more complicated forms of array and record aggregates
350 using DWARF.
351
352 \subsection{Fortran Simple Array Example}
353 \label{app:fortranarrayexample}
354 Consider the \addtoindex{Fortran array}\addtoindexx{Fortran 90} source fragment in 
355 \addtoindexx{array type entry!examples}
356 Figure \referfol{fig:fortranarrayexamplesourcefragment}.
357
358 \begin{figure}[h]
359 \begin{lstlisting}
360         type array_ptr
361         real :: myvar
362         real, dimension (:), pointer :: ap
363         end type array_ptr
364         type(array_ptr), allocatable, dimension(:) :: arrayvar
365         allocate(arrayvar(20))
366         do i = 1, 20
367             allocate(arrayvar(i)%ap(i+10))
368         end do
369 \end{lstlisting}
370 \caption{Fortran array example: source fragment} 
371 \label{fig:fortranarrayexamplesourcefragment}
372 \end{figure}
373
374 For allocatable and pointer arrays, it is essentially required
375 by the \addtoindex{Fortran array} semantics that each array consist of 
376 \addtoindexx{descriptor!array}
377 two
378 \addtoindexx{array!descriptor for}
379 parts, which we here call 1) the descriptor and 2) the raw
380 data. (A descriptor has often been called a dope vector in
381 other contexts, although it is often a structure of some kind
382 rather than a simple vector.) Because there are two parts,
383 and because the lifetime of the descriptor is necessarily
384 longer than and includes that of the raw data, there must be
385 an address somewhere in the descriptor that points to the
386 raw data when, in fact, there is some (that is, when 
387 the \doublequote{variable} is allocated or associated).
388
389 For concreteness, suppose that a descriptor looks something
390 like the C structure in 
391 Figure \refersec{fig:fortranarrayexampledescriptorrepresentation}.
392 Note, however, that it is
393 a property of the design that 1) a debugger needs no builtin
394 knowledge of this structure and 2) there does not need to
395 be an explicit representation of this structure in the DWARF
396 input to the debugger.
397
398 \begin{figure}[h]
399 \begin{lstlisting}
400 struct desc {
401     long el_len;       // Element length
402     void * base;       // Address of raw data
403     int ptr_assoc : 1; // Pointer is associated flag
404     int ptr_alloc : 1; // Pointer is allocated flag
405     int num_dims  : 6; // Number of dimensions
406     struct dims_str {  // For each dimension...  
407         long low_bound;
408         long upper_bound;
409         long stride;
410     } dims[63];
411 };
412 \end{lstlisting}
413 \caption{Fortran array example: descriptor representation}
414 \label{fig:fortranarrayexampledescriptorrepresentation}
415 \end{figure}
416
417
418 In practice, of course, a \doublequote{real} descriptor will have
419 dimension substructures only for as many dimensions as are
420 specified in the \texttt{num\_dims} component. Let us use the notation
421 \texttt{desc\textless n\textgreater}   
422 to indicate a specialization of the \texttt{desc} struct in
423 which \texttt{n} is the bound for the \texttt{dims} component as well as the
424 contents of the \texttt{num\_dims} component.
425
426 Because the arrays considered here come in two parts, it is
427 necessary to distinguish the parts carefully. In particular,
428 the \doublequote{address of the variable} or equivalently, the \doublequote{base
429 address of the object} \emph{always} refers to the descriptor. For
430 arrays that do not come in two parts, an implementation can
431 provide a descriptor anyway, thereby giving it two parts. (This
432 may be convenient for general runtime support unrelated to
433 debugging.) In this case the above vocabulary applies as
434 stated. Alternatively, an implementation can do without a
435 descriptor, in which case the \doublequote{address of the variable,}
436 or equivalently the \doublequote{base address of the object}, refers
437 to the \doublequote{raw data} (the real data, the only thing around
438 that can be the object).
439
440 If an object has a descriptor, then the DWARF type for that
441 object will have a 
442 \DWATdatalocation{} 
443 attribute. If an object
444 does not have a descriptor, then usually the DWARF type for the
445 object will not have a 
446 \DWATdatalocation. 
447 (See the following
448 \addtoindex{Ada} example for a case where the type for an object without
449 a descriptor does have a 
450 \DWATdatalocation{} attribute. In
451 that case the object doubles as its own descriptor.)
452
453 The \addtoindex{Fortran} derived type \texttt{array\_ptr} can now be redescribed
454 in C\dash like terms that expose some of the representation as in
455
456 \begin{lstlisting}[numbers=none]
457 struct array_ptr {
458     float myvar;
459     desc<1> ap;
460 };
461 \end{lstlisting}
462
463 Similarly for variable \texttt{arrayvar}:
464 \begin{lstlisting}[numbers=none]
465 desc<1> arrayvar;
466 \end{lstlisting}
467
468 (Recall that \texttt{desc\textless 1\textgreater} 
469 indicates the 1\dash dimensional version of \texttt{desc}.)
470
471 \newpage
472 Finally, the following notation is useful:
473 \begin{enumerate}[1. ]
474 \item  sizeof(type): size in bytes of entities of the given type
475 \item offset(type, comp): offset in bytes of the comp component
476 within an entity of the given type
477 \end{enumerate}
478
479 The DWARF description is shown 
480 \addtoindexx{Fortran 90}
481 in Figure \refersec{fig:fortranarrayexampledwarfdescription}.
482
483 \begin{figure}[h]
484 \figurepart{1}{2}
485 \begin{dwflisting}
486 \begin{alltt}
487 ! Description for type of 'ap'
488 !
489 1\$: \DWTAGarraytype
490         ! No name, default (Fortran) ordering, default stride
491         \DWATtype(reference to REAL)
492         \DWATassociated(expression=    ! Test 'ptr\_assoc' \nolink{flag}
493             \DWOPpushobjectaddress
494             \DWOPlitn                ! where n == offset(ptr\_assoc)
495             \DWOPplus
496             \DWOPderef
497             \DWOPlitone                  ! mask for 'ptr\_assoc' \nolink{flag}
498             \DWOPand)
499         \DWATdatalocation(expression= ! Get raw data address
500             \DWOPpushobjectaddress
501             \DWOPlitn                ! where n == offset(base)
502             \DWOPplus
503             \DWOPderef)                ! Type of index of array 'ap'
504 2\$:     \DWTAGsubrangetype
505             ! No name, default stride
506             \DWATtype(reference to INTEGER)
507             \DWATlowerbound(expression=
508                 \DWOPpushobjectaddress
509                 \DWOPlitn             ! where n ==
510                                          !   offset(desc, dims) +
511                                          !   offset(dims\_str, lower\_bound)
512                 \DWOPplus
513                 \DWOPderef)
514             \DWATupperbound(expression=
515                 \DWOPpushobjectaddress
516                 \DWOPlitn            ! where n ==
517                                         !   offset(desc, dims) +
518                                         !   offset(dims\_str, upper\_bound)
519                 \DWOPplus
520                 \DWOPderef)
521             !  Note: for the m'th dimension, the second operator becomes
522             !  \DWOPlitn where
523             !       n == offset(desc, dims)          +
524             !                (m-1)*sizeof(dims\_str)  +
525             !                 offset(dims\_str, [lower|upper]\_bound)
526             !  That is, the expression does not get longer for each successive 
527             !  dimension (other than to express the larger offsets involved).
528 \end{alltt}
529 \end{dwflisting}
530 \caption{Fortran array example: DWARF description}
531 \label{fig:fortranarrayexampledwarfdescription}
532 \end{figure}
533
534 \begin{figure}
535 \figurepart{2}{2}
536 \begin{dwflisting}
537 \begin{alltt}
538 3\$: \DWTAGstructuretype
539         \DWATname("array\_ptr")
540         \DWATbytesize(constant sizeof(REAL) + sizeof(desc<1>))
541 4\$:     \DWTAGmember
542             \DWATname("myvar")
543             \DWATtype(reference to REAL)
544             \DWATdatamemberlocation(constant 0)
545 5\$:     \DWTAGmember
546             \DWATname("ap");
547             \DWATtype(reference to 1\$)
548             \DWATdatamemberlocation(constant sizeof(REAL))
549 6\$: \DWTAGarraytype
550         ! No name, default (Fortran) ordering, default stride
551         \DWATtype(reference to 3\$)
552         \DWATallocated(expression=       ! Test 'ptr\_alloc' \nolink{flag}
553             \DWOPpushobjectaddress
554             \DWOPlitn                  ! where n == offset(ptr\_alloc)
555             \DWOPplus
556             \DWOPderef
557             \DWOPlittwo                    ! Mask for 'ptr\_alloc' \nolink{flag}
558             \DWOPand)
559         \DWATdatalocation(expression=   ! Get raw data address
560             \DWOPpushobjectaddress
561             \DWOPlitn                  ! where n == offset(base)
562             \DWOPplus
563             \DWOPderef)
564 7\$:     \DWTAGsubrangetype
565             ! No name, default stride
566             \DWATtype(reference to INTEGER)
567             \DWATlowerbound(expression=
568                 \DWOPpushobjectaddress
569                 \DWOPlitn              ! where n == ...
570                 \DWOPplus
571                 \DWOPderef)
572             \DWATupperbound(expression=
573                 \DWOPpushobjectaddress
574                 \DWOPlitn              ! where n == ...
575                 \DWOPplus
576                 \DWOPderef)
577 8\$: \DWTAGvariable
578         \DWATname("arrayvar")
579         \DWATtype(reference to 6\$)
580         \DWATlocation(expression=
581             ...as appropriate...)       ! Assume static allocation
582 \end{alltt}
583 \end{dwflisting}
584 \begin{center}
585 \vspace{3mm}
586 Figure~\ref{fig:fortranarrayexampledwarfdescription}: Fortran array example: DWARF description \textit{(concluded)}
587 \end{center}
588 \end{figure}
589
590 Suppose 
591 \addtoindexx{Fortran array example}
592 the program is stopped immediately following completion
593 of the do loop. Suppose further that the user enters the
594 following debug command:
595
596 \begin{lstlisting}[numbers=none]
597 debug> print arrayvar(5)%ap(2)
598 \end{lstlisting}
599
600 Interpretation of this expression proceeds as follows:
601 \begin{enumerate}[1. ]
602
603 \item Lookup name \texttt{arrayvar}. We find that it is a variable,
604 whose type is given by the unnamed type at 6\$. Notice that
605 the type is an array type.
606
607
608 \item Find the 5$^{th}$ element of that array object. To do array
609 indexing requires several pieces of information:
610 \begin{enumerate}[a) ]
611
612 \item  the address of the array data
613
614 \item the lower bounds of the array \\
615 % Using plain [] here gives trouble.
616 \lbrack To check that 5 is within bounds would require the upper
617 bound too, but we will skip that for this example. \rbrack
618
619 \item the stride 
620
621 \end{enumerate}
622
623 For a), check for a 
624 \DWATdatalocation{} attribute. 
625 Since there is one, go execute the expression, whose result is
626 the address needed. The object address used in this case
627 is the object we are working on, namely the variable named
628 \texttt{arrayvar}, whose address was found in step 1. (Had there been
629 no \DWATdatalocation{} attribute, the desired address would
630 be the same as the address from step 1.)
631
632 For b), for each dimension of the array (only one
633 in this case), go interpret the usual lower bound
634 attribute. Again this is an expression, which again begins
635 with \DWOPpushobjectaddress. This object is 
636 \textbf{still} \texttt{arrayvar},
637 from step 1, because we have not begun to actually perform
638 any indexing yet.
639
640 For c), the default stride applies. Since there is no
641 \DWATbytestride{} attribute, use the size of the array element
642 type, which is the size of type \texttt{array\_ptr} (at 3\$).
643
644 \clearpage
645
646 Having acquired all the necessary data, perform the indexing
647 operation in the usual manner--which has nothing to do with
648 any of the attributes involved up to now. Those just provide
649 the actual values used in the indexing step.
650
651 The result is an object within the memory that was dynamically
652 allocated for \texttt{arrayvar}.
653
654 \item  Find the \texttt{ap} component of the object just identified,
655 whose type is \texttt{array\_ptr}.
656
657 This is a conventional record component lookup and
658 interpretation. It happens that the \texttt{ap} component in this case
659 begins at offset 4 from the beginning of the containing object.
660 Component \texttt{ap} has the unnamed array type defined at 1\$ in the
661 symbol table.
662
663 \item  Find the second element of the array object found in step 3. To do array indexing requires
664 several pieces of information:
665 \begin{enumerate}[a) ]
666 \item  the address of the array storage
667
668 \item  the lower bounds of the array \\
669 % Using plain [] here gives trouble.
670 \lbrack To check that 2 is within bounds we would require the upper
671 bound too, but we will skip that for this example \rbrack
672
673 \item  the stride
674
675 \end{enumerate}
676 \end{enumerate}
677
678 This is just like step 2), so the details are omitted. Recall
679 that because the DWARF type 1\$ has a \DWATdatalocation,
680 the address that results from step 4) is that of a
681 descriptor, and that address is the address pushed by the
682 \DWOPpushobjectaddress{} operations in 1\$ and 2\$.
683
684 Note: we happen to be accessing a pointer array here instead
685 of an allocatable array; but because there is a common
686 underlying representation, the mechanics are the same. There
687 could be completely different descriptor arrangements and the
688 mechanics would still be the same---only the stack machines
689 would be different.
690
691 %\needlines{8}
692 \subsection{Fortran Coarray Examples}
693 \label{app:Fortrancoarrayexamples}
694
695 \subsubsection{Fortran Scalar Coarray Example}
696 The \addtoindex{Fortran} scalar coarray example
697 \addtoindexx{coarray!example}\addtoindexx{scalar coarray|see{coarray}}
698 in Figure \refersec{fig:Fortranscalarcoarraysourcefragment} can be described as 
699 illustrated in Figure \refersec{fig:FortranscalarcoarrayDWARFdescription}.
700
701 \begin{figure}[!h]
702 \begin{lstlisting}
703         INTEGER X[*]
704 \end{lstlisting}
705 \caption{Fortran scalar coarray: source fragment}
706 \label{fig:Fortranscalarcoarraysourcefragment}
707 \end{figure}
708
709 \begin{figure}[!h]
710 \begin{dwflisting}
711 \begin{alltt}
712 10\$:  \DWTAGcoarraytype
713         \DWATtype(reference to INTEGER)
714         \DWTAGsubrangetype                ! Note omitted upper bound                    
715             \DWATlowerbound(constant 1)
716
717 11\$:  \DWTAGvariable
718         \DWATname("X")
719         \DWATtype(reference to coarray type at 10\$)
720 \end{alltt}
721 \end{dwflisting}
722 \caption{Fortran scalar coarray: DWARF description}
723 \label{fig:FortranscalarcoarrayDWARFdescription}
724 \end{figure}
725
726 \subsubsection{Fortran Array Coarray Example}
727 The \addtoindex{Fortran} (simple) array coarray example
728 \addtoindexx{coarray!example}\addtoindexx{array coarray|see{coarray}}
729 in Figure \refersec{fig:Fortranarraycoarraysourcefragment} can be described as 
730 illustrated in Figure \refersec{fig:FortranarraycoarrayDWARFdescription}.
731
732 \begin{figure}[h]
733 \begin{lstlisting}
734         INTEGER X(10)[*]
735 \end{lstlisting}
736 \caption{Fortran array coarray: source fragment}
737 \label{fig:Fortranarraycoarraysourcefragment}
738 \end{figure}
739
740 \begin{figure}[h]
741 \begin{dwflisting}
742 \begin{alltt}
743 10\$: \DWTAGarraytype
744         \DWATordering(\DWORDcolmajor)
745         \DWATtype(reference to INTEGER)
746 11\$:    \DWTAGsubrangetype
747             \DWATlowerbound(constant 1)
748             \DWATupperbound(constant 10)
749
750 12\$: \DWTAGcoarraytype
751         \DWATtype(reference to array type at 10\$)
752 13\$:    \DWTAGsubrangetype                ! Note omitted upper bound
753             \DWATlowerbound(constant 1)
754
755 14$: \DWTAGvariable
756         \DWATname("X")
757         \DWATtype(reference to coarray type at 12\$)
758 \end{alltt}
759 \end{dwflisting}
760 \caption{Fortran array coarray: DWARF description}
761 \label{fig:FortranarraycoarrayDWARFdescription}
762 \end{figure}
763
764 \needlines{6}
765 \subsubsection{Fortran Multidimensional Coarray Example}
766 The \addtoindex{Fortran} multidimensional coarray of a multidimensional array example
767 \addtoindexx{coarray!example}\addtoindexx{array coarray|see{coarray}}
768 in Figure \refersec{fig:Fortranmultidimensionalcoarraysourcefragment} can be described as 
769 illustrated in Figure \referfol{fig:FortranmultidimensionalcoarrayDWARFdescription}.
770
771 \begin{figure}[h]
772 \begin{lstlisting}
773         INTEGER X(10,11,12)[2,3,*]
774 \end{lstlisting}
775 \caption{Fortran multidimensional coarray: source fragment}
776 \label{fig:Fortranmultidimensionalcoarraysourcefragment}
777 \end{figure}
778
779 \begin{figure}[h]
780 \begin{dwflisting}
781 \begin{alltt}
782 10\$: \DWTAGarraytype
783         \DWATordering(\DWORDcolmajor)
784         \DWATtype(reference to INTEGER)
785 11\$:    \DWTAGsubrangetype
786             \DWATlowerbound(constant 1)
787             \DWATupperbound(constant 10)
788 12\$:    \DWTAGsubrangetype
789             \DWATlowerbound(constant  1)
790             \DWATupperbound(constant 11)
791 13\$:    \DWTAGsubrangetype
792             \DWATlowerbound(constant  1)
793             \DWATupperbound(constant 12)
794
795 14\$: \DWTAGcoarraytype
796         \DWATtype(reference to array_type at 10\$)
797 15\$:    \DWTAGsubrangetype
798             \DWATlowerbound(constant 1)
799             \DWATupperbound(constant 2)
800 16\$:    \DWTAGsubrangetype
801             \DWATlowerbound(constant 1)
802             \DWATupperbound(constant 3)
803 17\$:    \DWTAGsubrangetype                ! Note omitted upper bound
804             \DWATlowerbound(constant 1)
805
806 18\$: \DWTAGvariable
807         \DWATname("X")
808         \DWATtype(reference to coarray type at 14\$)
809 \end{alltt}
810 \end{dwflisting}
811 \caption{Fortran multidimensional coarray: DWARF description}
812 \label{fig:FortranmultidimensionalcoarrayDWARFdescription}
813 \end{figure}
814
815
816 \clearpage
817 \subsection{Fortran 2008 Assumed-rank Array Example}
818 \label{app:assumedrankexample}
819 \addtoindexx{array!assumed-rank}
820 Consider the example in Figure~\ref{fig:assumedrankdecl}, which shows
821 an assumed-rank array in Fortran~2008 with
822 supplement~29113:\footnote{Technical Specification ISO/IEC TS
823   29113:2012 \emph{Further Interoperability of Fortran with C}}
824
825 \begin{figure}[!h]
826 \begin{lstlisting}
827   subroutine foo(x)
828     real :: x(..)
829
830     ! x has n dimensions
831   
832   end subroutine
833 \end{lstlisting}
834 \caption{Declaration of a Fortran 2008 assumed-rank array}
835 \label{fig:assumedrankdecl}
836 \end{figure}
837
838 Let's assume the Fortran compiler used an array descriptor that
839 (in \addtoindex{C}) looks
840 like the one shown in Figure~\ref{fig:arraydesc}.
841
842 \begin{figure}[!h]
843 \begin{lstlisting}
844   struct array_descriptor {
845     void *base_addr;
846     int rank;
847     struct dim dims[]; 
848   }
849
850   struct dim {
851      int lower_bound;
852      int upper_bound;
853      int stride;
854      int flags;
855   }
856 \end{lstlisting}
857 \caption{One of many possible layouts for an array descriptor}
858 \label{fig:arraydesc}
859 \end{figure}
860
861 The DWARF type for the array \emph{x} can be described as shown in
862 Figure~\refersec{fig:assumedrankdwarf}.
863
864 \begin{figure}[!h]
865 \begin{dwflisting}
866 \begin{alltt}
867 10\$:  \DWTAGarraytype
868          \DWATtype(reference to real)
869          \DWATrank(expression=
870              \DWOPpushobjectaddress
871              \DWOPlitn                        ! offset of rank in descriptor
872              \DWOPplus
873              \DWOPderef)
874          \DWATdatalocation(expression=
875              \DWOPpushobjectaddress
876              \DWOPlitn                        ! offset of data in descriptor
877              \DWOPplus
878              \DWOPderef)
879 11\$:    \DWTAGgenericsubrange
880              \DWATtype(reference to integer)
881              \DWATlowerbound(expression=
882              !   Looks up the lower bound of dimension i.
883              !   Operation                       ! Stack effect
884              !   (implicit)                      ! i                                                                     
885                  \DWOPlitn                    ! i sizeof(dim)
886                  \DWOPmul                       ! dim[i]
887                  \DWOPlitn                    ! dim[i] offsetof(dim)
888                  \DWOPplus                      ! dim[i]+offset
889                  \DWOPpushobjectaddress       ! dim[i]+offsetof(dim) objptr
890                  \DWOPplus                      ! objptr.dim[i]
891                  \DWOPlitn                    ! objptr.dim[i] offsetof(lb)
892                  \DWOPplus                      ! objptr.dim[i].lowerbound
893                  \DWOPderef)                    ! *objptr.dim[i].lowerbound
894              \DWATupperbound(expression=
895              !   Looks up the upper bound of dimension i.
896                  \DWOPlitn                    ! sizeof(dim)
897                  \DWOPmul
898                  \DWOPlitn                    ! offsetof(dim)
899                  \DWOPplus
900                  \DWOPpushobjectaddress
901                  \DWOPplus
902                  \DWOPlitn                    ! offset of upperbound in dim
903                  \DWOPplus
904                  \DWOPderef)
905              \DWATbytestride(expression=
906              !   Looks up the byte stride of dimension i.
907                  ...
908              !   (analogous to \DWATupperboundNAME)
909                  )
910 \end{alltt}
911 \end{dwflisting}
912 \caption{Sample DWARF for the array descriptor in Figure~\ref{fig:arraydesc}}
913 \label{fig:assumedrankdwarf}
914 \end{figure}
915
916 The layout of the array descriptor is not specified by the Fortran
917 standard unless the array is explicitly marked as \addtoindex{C-interoperable}. To
918 get the bounds of an assumed-rank array, the expressions in the
919 \DWTAGgenericsubrange{}
920 entry need to be evaluated for each of the
921 \DWATrank{} dimensions as shown by the pseudocode in
922 Figure~\refersec{fig:assumedrankdwarfparser}.
923
924 \begin{figure}[!h]
925 \begin{lstlisting}
926     typedef struct {
927         int lower, upper, stride;
928     } dims_t;
929
930     typedef struct {
931         int rank;
932     struct dims_t *dims;
933     } array_t;
934
935     array_t get_dynamic_array_dims(DW_TAG_array a) {
936       array_t result;
937
938       // Evaluate the DW_AT_rank expression to get the 
939       //    number of dimensions.
940       dwarf_stack_t stack;
941       dwarf_eval(stack, a.rank_expr);
942       result.rank = dwarf_pop(stack); 
943       result.dims = new dims_t[rank];
944
945       // Iterate over all dimensions and find their bounds.
946       for (int i = 0; i < result.rank; i++) {
947         // Evaluate the generic subrange's DW_AT_lower 
948         //    expression for dimension i.
949         dwarf_push(stack, i);
950         assert( stack.size == 1 );
951         dwarf_eval(stack, a.generic_subrange.lower_expr);
952         result.dims[i].lower = dwarf_pop(stack);
953         assert( stack.size == 0 );
954
955         dwarf_push(stack, i);
956         dwarf_eval(stack, a.generic_subrange.upper_expr);
957         result.dims[i].upper = dwarf_pop(stack);
958     
959         dwarf_push(stack, i);
960         dwarf_eval(stack, a.generic_subrange.byte_stride_expr);
961         result.dims[i].stride = dwarf_pop(stack);
962       }
963       return result;
964     }
965 \end{lstlisting}
966 \caption{How to interpret the DWARF from Figure~\ref{fig:assumedrankdwarf}}
967 \label{fig:assumedrankdwarfparser}
968 \end{figure}
969
970
971 \clearpage
972 \subsection{Fortran Dynamic Type Example}
973 \label{app:fortrandynamictypeexample}
974 Consider the \addtoindex{Fortran 90} example of dynamic properties in 
975 Figure \refersec{fig:fortrandynamictypeexamplesource}.
976 This can be represented in DWARF as illustrated in 
977 Figure \refersec{fig:fortrandynamictypeexampledwarfdescription}.
978 Note that unnamed dynamic types are used to avoid replicating
979 the full description of the underlying type \texttt{dt} that is shared by
980 several variables.
981
982 \begin{figure}[h]
983 \begin{lstlisting}
984             program sample
985      
986         type :: dt (l)
987             integer, len :: l
988             integer :: arr(l)
989         end type
990
991         integer :: n = 4
992         contains
993
994         subroutine s()
995             type (dt(n))               :: t1
996             type (dt(n)), pointer      :: t2
997             type (dt(n)), allocatable  :: t3, t4
998         end subroutine
999      
1000         end sample
1001 \end{lstlisting}
1002 \caption{Fortran dynamic type example: source}
1003 \label{fig:fortrandynamictypeexamplesource}
1004 \end{figure}
1005
1006 \begin{figure}[h]
1007 \begin{dwflisting}
1008 \begin{alltt}
1009 11$:    \DWTAGstructuretype
1010             \DWATname("dt")
1011             \DWTAGmember
1012                 ...
1013                         ...
1014
1015 13$:    \DWTAGdynamictype             ! plain version
1016             \DWATdatalocation (dwarf expression to locate raw data)
1017             \DWATtype (11$)
1018
1019 14$:    \DWTAGdynamictype             ! 'pointer' version
1020             \DWATdatalocation (dwarf expression to locate raw data)
1021             \DWATassociated (dwarf expression to test if associated)
1022             \DWATtype (11$)
1023
1024 15$:    \DWTAGdynamictype             ! 'allocatable' version
1025             \DWATdatalocation (dwarf expression to locate raw data)
1026             \DWATallocated (dwarf expression to test is allocated)
1027             \DWATtype (11$)
1028
1029 16$:    \DWTAGvariable
1030             \DWATname ("t1")
1031             \DWATtype (13$)
1032             \DWATlocation (dwarf expression to locate descriptor)
1033 17$:    \DWTAGvariable
1034             \DWATname ("t2")
1035             \DWATtype (14$)
1036             \DWATlocation (dwarf expression to locate descriptor)
1037 18$:    \DWTAGvariable
1038             \DWATname ("t3")
1039             \DWATtype (15$)
1040             \DWATlocation (dwarf expression to locate descriptor)
1041 19$:    \DWTAGvariable
1042             \DWATname ("t4")
1043             \DWATtype (15$)
1044             \DWATlocation (dwarf expression to locate descriptor)
1045 \end{alltt}
1046 \end{dwflisting}
1047 \caption{Fortran dynamic type example: DWARF description}
1048 \label{fig:fortrandynamictypeexampledwarfdescription}
1049 \end{figure}
1050
1051 \clearpage
1052 \subsection{C/C++ Anonymous Structure Example}
1053 \label{app:ccxxanonymousstructureexample}
1054 \addtoindexx{anonymous structure}
1055 An example of a \addtoindex{C}/\addtoindex{C++} structure is shown in
1056 Figure \ref{fig:anonymousstructureexamplesourcefragment}. 
1057 For this source, the DWARF description in 
1058 Figure \ref{fig:anonymousstructureexampledwarfdescription}
1059 is appropriate. In this example, \texttt{b} is referenced as if it 
1060 were defined in the enclosing structure \texttt{foo}.
1061
1062 \begin{figure}[h]
1063 \begin{lstlisting}
1064 struct foo {
1065     int a;
1066     struct {
1067         int b;
1068     };
1069 } x;
1070
1071 void bar(void)
1072 {
1073     struct foo t;
1074     t.a = 1;
1075     t.b = 2;
1076 }
1077
1078 \end{lstlisting}
1079 \caption{Anonymous structure example: source fragment}
1080 \label{fig:anonymousstructureexamplesourcefragment}
1081 \end{figure}
1082
1083 \begin{figure}[h]
1084 \begin{dwflisting}
1085 \begin{alltt}
1086 1$:   \DWTAGstructuretype  
1087           \DWATname("foo")
1088 2$:       \DWTAGmember
1089               \DWATname("a")
1090 3$:       \DWTAGstructuretype
1091               \DWATexportsymbols
1092 4$:           \DWTAGmember
1093                   \DWATname("b")
1094 \end{alltt}
1095 \end{dwflisting}
1096 \caption{Anonymous structure example: DWARF description}
1097 \label{fig:anonymousstructureexampledwarfdescription}
1098 \end{figure}
1099
1100 \subsection{Ada Example}
1101 \label{app:adaexample}
1102 Figure \refersec{fig:adaexamplesourcefragment}
1103 illustrates two kinds of \addtoindex{Ada} 
1104 parameterized array, one embedded in a record.
1105
1106 \begin{figure}[h]
1107 \begin{lstlisting}
1108 M : INTEGER := <exp>;
1109 VEC1 : array (1..M) of INTEGER;
1110 subtype TEENY is INTEGER range 1..100;
1111 type ARR is array (INTEGER range <>) of INTEGER;
1112 type REC2(N : TEENY := 100) is record
1113     VEC2 : ARR(1..N);
1114 end record;
1115
1116 OBJ2B : REC2;
1117 \end{lstlisting}
1118 \caption{Ada example: source fragment}
1119 \label{fig:adaexamplesourcefragment}
1120 \end{figure}
1121
1122 \texttt{VEC1} illustrates an (unnamed) array type where the upper bound
1123 of the first and only dimension is determined at runtime. 
1124 \addtoindex{Ada}
1125 semantics require that the value of an array bound is fixed at
1126 the time the array type is elaborated (where \textit{elaboration} refers
1127 to the runtime executable aspects of type processing). For
1128 the purposes of this example, we assume that there are no
1129 other assignments to \texttt{M} so that it safe for the \texttt{REC1} type
1130 description to refer directly to that variable (rather than
1131 a compiler-generated copy).
1132
1133 \texttt{REC2} illustrates another array type (the unnamed type of
1134 component \texttt{VEC2}) where the upper bound of the first and only
1135 bound is also determined at runtime. In this case, the upper
1136 bound is contained in a discriminant of the containing record
1137 type. (A \textit{discriminant} is a component of a record whose value
1138 cannot be changed independently of the rest of the record
1139 because that value is potentially used in the specification
1140 of other components of the record.)
1141
1142 The DWARF description is shown in 
1143 Figure \refersec{fig:adaexampledwarfdescription}.
1144
1145
1146 Interesting aspects about this example are:
1147 \begin{enumerate}[1. ]
1148 \item The array \texttt{VEC2} is \doublequote{immediately} contained within structure
1149 \texttt{REC2} (there is no intermediate descriptor or indirection),
1150 which is reflected in the absence of a \DWATdatalocation{}
1151 attribute on the array type at 28\$.
1152
1153 \item One of the bounds of \texttt{VEC2} is nonetheless dynamic and part of
1154 the same containing record. It is described as a reference to
1155 a member, and the location of the upper bound is determined
1156 as for any member. That is, the location is determined using
1157 an address calculation relative to the base of the containing
1158 object.  
1159
1160 A consumer must notice that the referenced bound is a
1161 member of the same containing object and implicitly push the
1162 base address of the containing object just as for accessing
1163 a data member generally.
1164
1165 \item The lack of a subtype concept in DWARF means that DWARF types
1166 serve the role of subtypes and must replicate information from
1167 what should be the parent type. For this reason, DWARF for
1168 the unconstrained array type \texttt{ARR} is not needed for the purposes
1169 of this example and therefore is not shown.
1170 \end{enumerate}
1171
1172 \begin{figure}[p]
1173 \begin{dwflisting}
1174 \begin{alltt}
1175 11\$: \DWTAGvariable
1176         \DWATname("M")
1177         \DWATtype(reference to INTEGER)
1178 12\$: \DWTAGarraytype
1179         ! No name, default (\addtoindex{Ada}) order, default stride
1180         \DWATtype(reference to INTEGER)
1181 13\$:    \DWTAGsubrangetype
1182             \DWATtype(reference to INTEGER)
1183             \DWATlowerbound(constant 1)
1184             \DWATupperbound(reference to variable M at 11\$)
1185 14\$: \DWTAGvariable
1186         \DWATname("VEC1")
1187         \DWATtype(reference to array type at 12\$)
1188      . . .
1189 21\$: \DWTAGsubrangetype
1190         \DWATname("TEENY")
1191         \DWATtype(reference to INTEGER)
1192         \DWATlowerbound(constant 1)
1193         \DWATupperbound(constant 100)
1194      . . .
1195 26\$: \DWTAGstructuretype
1196         \DWATname("REC2")
1197 27\$:    \DWTAGmember
1198             \DWATname("N")
1199             \DWATtype(reference to subtype TEENY at 21\$)
1200             \DWATdatamemberlocation(constant 0)
1201 28\$:    \DWTAGarraytype
1202             ! No name, default (\addtoindex{Ada}) order, default stride
1203             ! Default data location
1204             \DWATtype(reference to INTEGER)
1205 29\$:        \DWTAGsubrangetype
1206                 \DWATtype(reference to subrange TEENY at 21\$)
1207                 \DWATlowerbound(constant 1)
1208                 \DWATupperbound(reference to member N at 27\$)
1209 30\$:    \DWTAGmember
1210             \DWATname("VEC2")
1211             \DWATtype(reference to array "subtype" at 28\$)
1212             \DWATdatamemberlocation(machine=
1213                 \DWOPlitn                  ! where n == offset(REC2, VEC2)
1214                 \DWOPplus)
1215      . . .
1216 41\$: \DWTAGvariable
1217         \DWATname("OBJ2B")
1218         \DWATtype(reference to REC2 at 26\$)
1219         \DWATlocation(...as appropriate...)
1220 \end{alltt}
1221 \end{dwflisting}
1222 \caption{Ada example: DWARF description}
1223 \label{fig:adaexampledwarfdescription}
1224 \end{figure}
1225
1226 \clearpage
1227
1228 \subsection{Pascal Example}
1229 \label{app:pascalexample}
1230 The Pascal \addtoindexx{Pascal example} source in 
1231 Figure \referfol{fig:packedrecordexamplesourcefragment}
1232 is used to illustrate the representation of packed unaligned
1233 \addtoindex{bit fields}.
1234
1235 \begin{figure}[h]
1236 \begin{lstlisting}
1237 TYPE T : PACKED RECORD                  ! bit size is 2
1238          F5 : BOOLEAN;                  ! bit offset is 0
1239          F6 : BOOLEAN;                  ! bit offset is 1
1240          END;
1241 VAR V :  PACKED RECORD
1242          F1 : BOOLEAN;                  ! bit offset is 0
1243          F2 : PACKED RECORD             ! bit offset is 1
1244               F3 : INTEGER;             ! bit offset is 0 in F2, 1 in V
1245               END;
1246          F4 : PACKED ARRAY [0..1] OF T; ! bit offset is 33
1247          F7 : T;                        ! bit offset is 37
1248          END;
1249 \end{lstlisting}
1250 \caption{Packed record example: source fragment}
1251 \label{fig:packedrecordexamplesourcefragment}
1252 \end{figure}
1253
1254 The DWARF representation in 
1255 Figure \refersec{fig:packedrecordexampledwarfdescription} 
1256 is appropriate. 
1257 \DWTAGpackedtype{} entries could be added to
1258 better represent the source, but these do not otherwise affect
1259 the example and are omitted for clarity. Note that this same
1260 representation applies to both typical big- and 
1261 little-endian
1262 architectures using the conventions described in 
1263 Section \refersec{chap:datamemberentries}.
1264
1265 \begin{figure}[h]
1266 \figurepart{1}{2}
1267 \begin{dwflisting}
1268 \begin{alltt}
1269 10\$: \DWTAGbasetype
1270         \DWATname("BOOLEAN")
1271             ...
1272 11\$: \DWTAGbasetype
1273         \DWATname("INTEGER")
1274             ...
1275 20\$: \DWTAGstructuretype
1276         \DWATname("T")
1277         \DWATbitsize(2)
1278         \DWTAGmember
1279             \DWATname("F5")
1280             \DWATtype(reference to 10$)
1281             \DWATdatabitoffset(0)        ! may be omitted
1282             \DWATbitsize(1)
1283 \end{alltt}
1284 \end{dwflisting}
1285 \caption{Packed record example: DWARF description}
1286 \label{fig:packedrecordexampledwarfdescription}
1287 \end{figure}
1288
1289 \begin{figure}[h]
1290 \figurepart{2}{2}
1291 \begin{dwflisting}
1292 \begin{alltt}
1293         \DWTAGmember
1294             \DWATname("F6")
1295             \DWATtype(reference to 10$)
1296             \DWATdatabitoffset(1)
1297             \DWATbitsize(1)
1298 21\$: \DWTAGstructuretype                  ! anonymous type for F2
1299         \DWTAGmember
1300             \DWATname("F3")
1301             \DWATtype(reference to 11\$)
1302 22\$: \DWTAGarraytype                      ! anonymous type for F4
1303         \DWATtype(reference to 20\$)
1304         \DWTAGsubrangetype
1305             \DWATtype(reference to 11\$)
1306             \DWATlowerbound(0)
1307             \DWATupperbound(1)
1308         \DWATbitstride(2)
1309         \DWATbitsize(4) \addtoindexx{bit size attribute}
1310 23\$: \DWTAGstructuretype                  ! anonymous type for V
1311         \DWATbitsize(39) \addtoindexx{bit size attribute}
1312         \DWTAGmember
1313             \DWATname("F1")
1314             \DWATtype(reference to 10\$)
1315             \DWATdatabitoffset(0)        ! may be omitted
1316             \DWATbitsize(1) ! may be omitted
1317         \DWTAGmember
1318             \DWATname("F2")
1319             \DWATtype(reference to 21\$)
1320             \DWATdatabitoffset(1)
1321             \DWATbitsize(32) ! may be omitted
1322         \DWTAGmember
1323             \DWATname("F4")
1324             \DWATtype(reference to 22\$)
1325             \DWATdatabitoffset(33)
1326             \DWATbitsize(4) ! may be omitted
1327         \DWTAGmember
1328             \DWATname("F7")
1329             \DWATtype(reference to 20\$)    ! type T
1330             \DWATdatabitoffset(37)
1331             \DWATbitsize(2) \addtoindexx{bit size attribute}              ! may be omitted
1332      \DWTAGvariable
1333         \DWATname("V")
1334         \DWATtype(reference to 23\$)
1335         \DWATlocation(...)
1336         ...
1337 \end{alltt}
1338 \end{dwflisting}
1339 \begin{center}
1340 \vspace{3mm}
1341 Figure~\ref{fig:packedrecordexampledwarfdescription}: Packed record example: DWARF description \textit{(concluded)}
1342 \end{center}
1343 \end{figure}
1344
1345 \clearpage
1346 \subsection{C/C++ Bit-Field Examples}
1347 \label{app:ccppbitfieldexamples}
1348 \textit{Bit fields\addtoindexx{bit fields} in \addtoindex{C} 
1349 and \addtoindex{C++} typically require the use of the
1350 \DWATdatabitoffset{}\addtoindexx{data bit offset}
1351 and \DWATbitsize{}\addtoindexx{data bit size} attributes.}
1352
1353 \needlines{6}
1354 \textit{This Standard uses the following bit numbering and direction
1355 conventions in examples. These conventions are for illustrative
1356 purposes and other conventions may apply on particular
1357 architectures.}
1358 \begin{itemize}
1359 \item \textit{For big-endian architectures, bit offsets are
1360 counted from high-order to low-order bits within a byte (or
1361 larger storage unit); in this case, the bit offset identifies
1362 the high-order bit of the object.}
1363
1364 \item \textit{For little-endian architectures, bit offsets are
1365 counted from low-order to high-order bits within a byte (or
1366 larger storage unit); in this case, the bit offset identifies
1367 the low-order bit of the object.}
1368 \end{itemize}
1369
1370 \textit{In either case, the bit so identified is defined as the 
1371 \addtoindexx{beginning of an object}
1372 beginning of the object.}
1373
1374 \needlines{5}
1375 This section illustrates one possible representation of the 
1376 following \addtoindex{C} structure definition in both big- 
1377 and little-endian \byteorder{s}:
1378
1379 \begin{lstlisting}
1380 struct S {
1381     int j:5;
1382     int k:6;
1383     int m:5;
1384     int n:8;
1385 };
1386 \end{lstlisting}
1387
1388 Figures \ref{fig:bigendiandatabitoffsets} and
1389 \refersec{fig:littleendiandatabitoffsets}
1390 show the structure layout
1391 and data bit offsets for example big- and little-endian
1392 architectures, respectively. Both diagrams show a structure
1393 that begins at address A and whose size is four bytes. Also,
1394 high order bits are to the left and low order bits are to
1395 the right.
1396
1397 \begin{figure}[h]
1398 \begin{dwflisting}
1399 \begin{verbatim}
1400
1401     j:0
1402     k:5
1403     m:11
1404     n:16
1405
1406     Addresses increase ->
1407     |       A       |     A + 1     |    A + 2      |    A + 3      | 
1408
1409     Data bit offsets increase ->
1410     +---------------+---------------+---------------+---------------+
1411     |0     4|5         10|11      15|16           23|24           31|
1412     |   j   |     k      | m        |        n      |       <pad>   |
1413     |       |            |          |               |               | 
1414     +---------------------------------------------------------------+ 
1415
1416 \end{verbatim}
1417 \end{dwflisting}
1418 \caption{Big-endian data bit offsets}
1419 \label{fig:bigendiandatabitoffsets}
1420 \end{figure}
1421
1422 \begin{figure}[h]
1423 \begin{dwflisting}
1424 \begin{verbatim}
1425
1426     j:0
1427     k:5
1428     m:11
1429     n:16
1430                                                <- Addresses increase
1431     |     A + 3     |     A + 2     |    A + 1      |       A       | 
1432
1433                                         <-  Data bit offsets increase 
1434     +---------------+---------------+---------------+---------------+
1435     |31           24|23           16|15     11|10       5|4        0|
1436     |     <pad>     |        n      |    m    |    k     |     j    |
1437     |               |               |         |          |          |
1438     +---------------------------------------------------------------+
1439
1440 \end{verbatim}
1441 \end{dwflisting}
1442 \caption{Little-endian data bit offsets}
1443 \label{fig:littleendiandatabitoffsets}
1444 \end{figure}
1445
1446 \needlines{4}
1447 Note that data member bit offsets in this example are the
1448 same for both big- and little-endian architectures even
1449 though the fields are allocated in different directions
1450 (high-order to low-order versus low-order to high-order);
1451 the bit naming conventions for memory and/or registers of
1452 the target architecture may or may not make this seem natural.
1453
1454 \clearpage
1455 \section{Namespace Examples}
1456 \label{app:namespaceexamples}
1457
1458 The \addtoindex{C++} example in 
1459 Figure \refersec{fig:namespaceexample1sourcefragment}
1460 is used 
1461 \addtoindexx{namespace (C++)!example}
1462 to illustrate the representation of namespaces.
1463 The DWARF representation in 
1464 Figure \refersec{fig:namespaceexample1dwarfdescription}
1465 is appropriate.
1466
1467 \begin{figure}[h]
1468 \begin{lstlisting}
1469 namespace {
1470     int i;
1471 }
1472 namespace A {
1473     namespace B {
1474         int j;
1475         int   myfunc (int a);
1476         float myfunc (float f) { return f - 2.0; }
1477         int   myfunc2(int a)   { return a + 2; }
1478     }
1479 }
1480 namespace Y {
1481     using A::B::j;         // (1) using declaration
1482     int foo;
1483 }
1484 using A::B::j;             // (2) using declaration
1485 namespace Foo = A::B;      // (3) namespace alias
1486 using Foo::myfunc;         // (4) using declaration
1487 using namespace Foo;       // (5) using directive
1488 namespace A {
1489     namespace B {
1490         using namespace Y; // (6) using directive
1491         int k;
1492     }
1493 }
1494 int Foo::myfunc(int a)
1495 {
1496     i = 3;
1497     j = 4;
1498     return myfunc2(3) + j + i + a + 2;
1499 }
1500 \end{lstlisting}
1501 \caption{Namespace example \#1: source fragment}
1502 \label{fig:namespaceexample1sourcefragment}
1503 \end{figure}
1504
1505
1506 \begin{figure}[p]
1507 \figurepart{1}{2}
1508 \begin{dwflisting}
1509 \begin{alltt}
1510
1511 1\$:  \DWTAGbasetype
1512         \DWATname("int")
1513         ...
1514 2\$:  \DWTAGbasetype
1515         \DWATname("float")
1516         ...
1517 6\$:  \DWTAGnamespace
1518         ! no \DWATname attribute
1519 7\$:
1520         \DWTAGvariable
1521             \DWATname("i")
1522             \DWATtype(reference to 1\$)
1523             \DWATlocation ...
1524             ...
1525 10\$: \DWTAGnamespace
1526         \DWATname("A")
1527 20\$:    \DWTAGnamespace
1528             \DWATname("B")
1529 30\$:        \DWTAGvariable
1530                 \DWATname("j")
1531                 \DWATtype(reference to 1\$)
1532                 \DWATlocation ...
1533                 ...
1534 34\$:        \DWTAGsubprogram
1535                 \DWATname("myfunc")
1536                 \DWATtype(reference to 1\$)
1537                 ...
1538 36\$:        \DWTAGsubprogram
1539                 \DWATname("myfunc")
1540                 \DWATtype(reference to 2\$)
1541                 ...
1542 38\$:        \DWTAGsubprogram
1543                 \DWATname("myfunc2")
1544                 \DWATlowpc ...
1545                 \DWAThighpc ...
1546                 \DWATtype(reference to 1\$)
1547                 ...
1548 \end{alltt}
1549 \end{dwflisting}
1550 \caption{Namespace example \#1: DWARF description}
1551 \label{fig:namespaceexample1dwarfdescription}
1552 \end{figure}
1553
1554 \begin{figure}
1555 \figurepart{2}{2}
1556 \begin{dwflisting}
1557 \begin{alltt}
1558 40\$: \DWTAGnamespace
1559         \DWATname("Y")
1560         \DWTAGimporteddeclaration            ! (1) using-declaration
1561             \DWATimport(reference to 30\$)
1562         \DWTAGvariable
1563             \DWATname("foo")
1564             \DWATtype(reference to 1\$)
1565             \DWATlocation ...
1566             ...
1567      \DWTAGimporteddeclaration               ! (2) using declaration
1568         \DWATimport(reference to 30\$)
1569         \DWTAGimporteddeclaration            ! (3) namespace alias
1570             \DWATname("Foo")
1571             \DWATimport(reference to 20\$)
1572         \DWTAGimporteddeclaration            ! (4) using declaration
1573             \DWATimport(reference to 34\$)     !     - part 1
1574         \DWTAGimporteddeclaration            ! (4) using declaration
1575             \DWATimport(reference to 36\$)     !     - part 2
1576         \DWTAGimportedmodule                 ! (5) using directive
1577             \DWATimport(reference to 20\$)
1578         \DWTAGnamespace
1579             \DWATextension(reference to 10\$)
1580             \DWTAGnamespace
1581                 \DWATextension(reference to 20\$)
1582                 \DWTAGimportedmodule         ! (6) using directive
1583                     \DWATimport(reference to 40\$)
1584                 \DWTAGvariable
1585                     \DWATname("k")
1586                     \DWATtype(reference to 1\$)
1587                     \DWATlocation ...
1588                     ...
1589 60\$: \DWTAGsubprogram
1590         \DWATspecification(reference to 34\$)
1591         \DWATlowpc ...
1592         \DWAThighpc ...
1593         ...
1594 \end{alltt}
1595 \end{dwflisting}
1596 \begin{center}
1597 \vspace{3mm}
1598 Figure~\ref{fig:namespaceexample1dwarfdescription}: Namespace example \#1: DWARF description \textit{(concluded)}
1599 \end{center}
1600 \end{figure}
1601
1602 \clearpage
1603 As a further namespace example, consider the inlined namespace shown in
1604 Figure \refersec{fig:namespaceexample2sourcefragment}. For this source,
1605 the DWARF description in Figure \ref{fig:namespaceexample2dwarfdescription}
1606 is appropriate. In this example, \texttt{a} may be referenced either as a member of 
1607 the fully qualified namespace \texttt{A::B}, or as if it were defined
1608 in the enclosing namespace, \texttt{A}.
1609
1610 \begin{figure}[h]
1611 \begin{lstlisting}
1612 namespace A {
1613     inline namespace B {   // (1) inline namespace
1614         int a;
1615     }
1616 }
1617
1618 void foo (void)
1619 {
1620     using A::B::a;
1621     a = 1;
1622 }
1623
1624 void bar (void)
1625 {
1626     using A::a;
1627     a = 2;
1628 }
1629 \end{lstlisting}
1630 \caption{Namespace example \#2: source fragment}
1631 \label{fig:namespaceexample2sourcefragment}
1632 \end{figure}
1633
1634 \begin{figure}[h]
1635 \begin{dwflisting}
1636 \begin{alltt}
1637 1$:   \DWTAGnamespace
1638           \DWATname("A")       
1639 2$:       \DWTAGnamespace
1640               \DWATname("B")      
1641               \DWATexportsymbols     
1642 3$:           \DWTAGvariable
1643                   \DWATname("a")       
1644 \end{alltt}
1645 \end{dwflisting}
1646 \caption{Namespace example \#2: DWARF description}
1647 \label{fig:namespaceexample2dwarfdescription}
1648 \end{figure}
1649
1650 \clearpage
1651 \section{Member Function Examples}
1652 \label{app:memberfunctionexample}
1653 \addtoindexx{member function example}
1654 Consider the member function example fragment in 
1655 Figure \refersec{fig:memberfunctionexamplesourcefragment}.
1656 The DWARF representation in 
1657 Figure \refersec{fig:memberfunctionexampledwarfdescription}
1658 is appropriate.
1659
1660 \begin{figure}[h]
1661 \begin{lstlisting}
1662 class A
1663 {
1664     void func1(int x1);
1665     void func2() const;
1666     static void func3(int x3);
1667 };
1668 void A::func1(int x) {}
1669 \end{lstlisting}
1670 \caption{Member function example: source fragment}
1671 \label{fig:memberfunctionexamplesourcefragment}
1672 \end{figure}
1673
1674 \begin{figure}[h]
1675 \figurepart{1}{2}
1676 \begin{dwflisting}
1677 \begin{alltt}
1678
1679 2\$: \DWTAGbasetype
1680         \DWATname("int")
1681         ...
1682 3\$: \DWTAGclasstype
1683         \DWATname("A")
1684         ...
1685 4\$:     \DWTAGpointertype
1686             \DWATtype(reference to 3\$)
1687             ...
1688 5\$:     \DWTAGconsttype
1689             \DWATtype(reference to 3\$)
1690             ...
1691 6\$:     \DWTAGpointertype
1692             \DWATtype(reference to 5\$)
1693             ...
1694
1695 7\$:     \DWTAGsubprogram
1696             \DWATdeclaration
1697             \DWATname("func1")
1698             \DWATobjectpointer(reference to 8\$) \addtoindexx{object pointer attribute}
1699                 ! References a formal parameter in this 
1700                 ! member function
1701             ...
1702
1703 \end{alltt}
1704 \end{dwflisting}
1705 \caption{Member function example: DWARF description}
1706 \label{fig:memberfunctionexampledwarfdescription}
1707 \end{figure}
1708
1709 \begin{figure}[p]
1710 \figurepart{2}{2}
1711 \begin{dwflisting}
1712 \begin{alltt}
1713
1714 8\$:         \DWTAGformalparameter
1715                 \DWATartificial(true)
1716                 \DWATname("this")
1717                 \DWATtype(reference to 4\$)
1718                     ! Makes type of 'this' as 'A*' =>
1719                     ! func1 has not been marked const 
1720                     ! or volatile
1721                 \DWATlocation ...
1722                 ...
1723 9\$:         \DWTAGformalparameter
1724                 \DWATname(x1)
1725                 \DWATtype(reference to 2\$)
1726                 ...
1727 10\$:    \DWTAGsubprogram
1728             \DWATdeclaration
1729             \DWATname("func2")
1730             \DWATobjectpointer(reference to 11\$) \addtoindexx{object pointer attribute}
1731             ! References a formal parameter in this 
1732             ! member function
1733             ...
1734 11\$:        \DWTAGformalparameter
1735                 \DWATartificial(true)
1736                 \DWATname("this")
1737                 \DWATtype(reference to 6\$)
1738                 ! Makes type of 'this' as 'A const*' =>
1739                 !     func2 marked as const
1740                 \DWATlocation ...
1741                 ...
1742 12\$:    \DWTAGsubprogram
1743             \DWATdeclaration
1744             \DWATname("func3")
1745             ...
1746                 ! No object pointer reference formal parameter
1747                 ! implies func3 is static
1748 13\$:        \DWTAGformalparameter
1749                 \DWATname(x3)
1750                 \DWATtype(reference to 2\$)
1751                 ...
1752
1753 \end{alltt}
1754 \end{dwflisting}
1755 \begin{center}
1756 \vspace{3mm}
1757 Figure~\ref{fig:memberfunctionexampledwarfdescription}: Member function example: DWARF description \textit{(concluded)}
1758 \end{center}
1759 \end{figure}
1760
1761 \clearpage
1762 As a further example illustrating \&- and \&\&-qualification
1763 of member functions, 
1764 consider the member function example fragment in 
1765 Figure \refersec{fig:memberfunctionrefqualexamplesourcefragment}.
1766 The DWARF representation in 
1767 Figure \refersec{fig:memberfunctionrefqualexampledwarfdescription}
1768 is appropriate.
1769
1770 \begin{figure}[h]
1771 \begin{lstlisting}
1772 class A {
1773 public:
1774     void f() const &&;
1775 };
1776    
1777 void g() {
1778     A a;
1779     // The type of pointer is "void (A::*)() const &&".
1780     auto pointer_to_member_function = &A::f;
1781 }
1782 \end{lstlisting}
1783 \caption{Reference- and rvalue-reference-qualification example: source \mbox{fragment}}
1784 \label{fig:memberfunctionrefqualexamplesourcefragment}
1785 \end{figure}
1786
1787 \begin{figure}[h]
1788 %\figurepart{1}{2}
1789 \begin{dwflisting}
1790 \begin{alltt}
1791
1792 100$:   \DWTAGclasstype
1793             \DWATname("A")
1794             \DWTAGsubprogram
1795                 \DWATname("f")
1796                 \DWATrvaluereference(0x01)
1797                 \DWTAGformalparameter
1798                     \DWATtype({ref to 200$})    ! to const A*
1799                     \DWATartificial(0x01)
1800
1801 200$:   ! const A*
1802         \DWTAGpointertype
1803             \DWATtype({ref to 300$})             ! to const A
1804
1805 300$:   ! const A
1806         \DWTAGconsttype
1807             \DWATtype({ref to 100$})             ! to class A
1808
1809 400$:   ! mfptr
1810         \DWTAGptrtomembertype
1811             \DWATtype({ref to 400$})             ! to functype
1812             \DWATcontainingtype({ref to 100$})  ! to class A
1813
1814 500$:   ! functype
1815         \DWTAGsubroutinetype
1816             \DWATrvaluereference(0x01)
1817             \DWTAGformalparameter
1818                 \DWATtype({ref to 200$})         ! to const A*
1819                 \DWATartificial(0x01)
1820
1821 600$:   \DWTAGsubprogram
1822             \DWATname("g")
1823             \DWTAGvariable
1824                 \DWATname("a")
1825                 \DWATtype({ref to 100$})         ! to class A
1826             \DWTAGvariable
1827                 \DWATname("pointer_to_member_function")
1828                 \DWATtype({ref to 300$})
1829          
1830 \end{alltt}
1831 \end{dwflisting}
1832 % The extra ~ at the end of the following caption is present to get the entry in the
1833 % List of Figures to wrap the page number properly (to align the numbers)...
1834 \caption{Reference- and rvalue-reference-qualification example: DWARF \mbox{description} ~}
1835 \label{fig:memberfunctionrefqualexampledwarfdescription}
1836 \end{figure}
1837
1838
1839 \clearpage
1840 \section{Line Number Examples}
1841 \label{app:linenumberexamples}
1842
1843 \subsection{Line Number Header Example}
1844 \label{app:linenumberheaderexample}
1845
1846 The information found in a \DWARFVersionIV{} line number 
1847 header can be encoded as shown in 
1848 Figure \refersec{fig:preV5LNCTusingV5}.
1849
1850 \begin{figure}[h]
1851 \begin{dwflisting}
1852 \begin{alltt}
1853   Field           Field Name                      Value(s)
1854   Number
1855      1    \textit{Same as in Version 4}            ...
1856      2    version                         5
1857      3    \textit{Not present in Version 4}        -
1858      4    \textit{Not present in Version 4}        -
1859    5-12   \textit{Same as in Version 4}            ...
1860     13    \HFNdirectoryentryformatcount{}    1
1861     14    \HFNdirectoryentryformat{}          \DWLNCTpath, \DWFORMstring
1862     15    \HFNdirectoriescount{}               <n>
1863     16    \HFNdirectories{}                     <n>*<null terminated string>
1864     17    \HFNfilenameentryformatcount{}    4
1865     18    \HFNfilenameentryformat{}          \DWLNCTpath, \DWFORMstring,
1866                                           \DWLNCTdirectoryindex, \DWFORMudata,
1867                                           \DWLNCTtimestamp, \DWFORMudata,
1868                                           \DWLNCTsize, \DWFORMudata
1869     19    \HFNfilenamescount{}                <m>
1870     20    \HFNfilenames{}                      <m>*\{<null terminated string>, <index>, 
1871                                                <timestamp>, <size>\}
1872 \end{alltt}
1873 \end{dwflisting}
1874 \begin{centering}
1875 \caption{Pre-\DWARFVersionV{} line number program header information \mbox{encoded} using \DWARFVersionV}
1876 \label{fig:preV5LNCTusingV5}
1877 \end{centering}
1878 \end{figure}
1879
1880 \subsection{Line Number Special Opcode Example}
1881 \label{app:linenumberspecialopcodeexample}
1882 Suppose that the opcode\_base is 13, 
1883 \addttindex{line\_base} is -3, 
1884 \addttindex{line\_range} is 12, 
1885 \addttindex{minimum\_instruction\_length} is 1
1886 and 
1887 \addttindex{maximum\_operations\_per\_instruction} is 1. 
1888 This means that
1889 we can use a special opcode whenever two successive rows in
1890 the matrix have source line numbers differing by any value
1891 within the range [-3, 8] and (because of the limited number
1892 of opcodes available) when the difference between addresses
1893 is within the range [0, 20], but not all line advances are
1894 available for the maximum \addtoindex{operation advance} (see below).
1895
1896 The resulting opcode mapping is shown in
1897 Figure \refersec{fig:examplelinenumberspecialopcodemapping}.
1898
1899 \begin{figure}[ht]
1900 \begin{alltt}
1901                         Line Advance
1902    Operation  
1903      Advance    -3  -2  -1   0   1   2   3   4   5   6   7   8
1904    ---------   -----------------------------------------------
1905            0    13  14  15  16  17  18  19  20  21  22  23  24
1906            1    25  26  27  28  29  30  31  32  33  34  35  36
1907            2    37  38  39  40  41  42  43  44  45  46  47  48
1908            3    49  50  51  52  53  54  55  56  57  58  59  60
1909            4    61  62  63  64  65  66  67  68  69  70  71  72
1910            5    73  74  75  76  77  78  79  80  81  82  83  84
1911            6    85  86  87  88  89  90  91  92  93  94  95  96
1912            7    97  98  99 100 101 102 103 104 105 106 107 108
1913            8   109 110 111 112 113 114 115 116 117 118 119 120
1914            9   121 122 123 124 125 126 127 128 129 130 131 132
1915           10   133 134 135 136 137 138 139 140 141 142 143 144
1916           11   145 146 147 148 149 150 151 152 153 154 155 156
1917           12   157 158 159 160 161 162 163 164 165 166 167 168
1918           13   169 170 171 172 173 174 175 176 177 178 179 180
1919           14   181 182 183 184 185 186 187 188 189 190 191 192
1920           15   193 194 195 196 197 198 199 200 201 202 203 204
1921           16   205 206 207 208 209 210 211 212 213 214 215 216
1922           17   217 218 219 220 221 222 223 224 225 226 227 228 
1923           18   229 230 231 232 233 234 235 236 237 238 239 240 
1924           19   241 242 243 244 245 246 247 248 249 250 251 252
1925           20   253 254 255
1926           
1927 \end{alltt}
1928 \caption{Example line number special opcode mapping}
1929 \label{fig:examplelinenumberspecialopcodemapping}
1930 \end{figure}
1931
1932 There is no requirement that the expression 
1933 255 - \addttindex{line\_base} + 1 be an integral multiple of
1934 \addttindex{line\_range}.
1935
1936
1937 \clearpage
1938 \subsection{Line Number Program Example}
1939 \label{app:linenumberprogramexample}
1940
1941 Consider the simple source file and the resulting machine
1942 code for the Intel 8086 processor in 
1943 Figure \refersec{fig:linenumberprogramexamplemachinecode}.
1944
1945 \begin{figure}[h]
1946 \begin{lstlisting}
1947 1: int
1948 2: main()
1949     0x239: push pb
1950     0x23a: mov bp,sp
1951 3: {
1952 4: printf("Omit needless words\n");
1953     0x23c: mov ax,0xaa
1954     0x23f: push ax
1955     0x240: call _printf
1956     0x243: pop cx
1957 5: exit(0);
1958     0x244: xor ax,ax
1959     0x246: push ax
1960     0x247: call _exit
1961     0x24a: pop cx
1962 6: }
1963     0x24b: pop bp
1964     0x24c: ret
1965 7: 0x24d:
1966 \end{lstlisting}
1967 \caption{Line number program example: machine code}
1968 \label{fig:linenumberprogramexamplemachinecode}
1969 \end{figure}
1970
1971 Suppose the line number program header includes the following
1972 (header fields not needed 
1973 \addttindexx{line\_base}
1974 below 
1975 \addttindexx{line\_range}
1976 are 
1977 \addttindexx{opcode\_base}
1978 not 
1979 \addttindexx{minimum\_instruction\_length}
1980 shown):
1981 \begin{alltt}
1982     version                       4
1983     minimum_instruction_length    1
1984     opcode_base                  10   ! Opcodes 10-12 not needed
1985     line_base                     1
1986     line_range                   15
1987 \end{alltt}
1988
1989
1990 Table \refersec{tab:linenumberprogramexampleoneencoding}
1991 shows one encoding of the line number program, which occupies
1992 12 bytes (the opcode SPECIAL(\textit{m},\textit{n}) indicates the special opcode
1993 generated for a line increment of \textit{m} and an address increment
1994 of \textit{n}).
1995
1996 \newpage
1997 \begin{centering}
1998 \setlength{\extrarowheight}{0.1cm}
1999 \begin{longtable}{l|l|l}
2000   \caption{Line number program example: one \mbox{encoding}}
2001   \label{tab:linenumberprogramexampleoneencoding} \\
2002   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
2003 \endfirsthead
2004   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
2005 \endhead
2006   \hline \emph{Continued on next page}
2007 \endfoot
2008   \hline
2009 \endlastfoot
2010 \DWLNSadvancepc&LEB128(0x239)&0x2, 0xb9, 0x04 \\
2011 SPECIAL(2, 0)& &0xb  \\
2012 SPECIAL(2, 3)& &0x38 \\
2013 SPECIAL(1, 8)& &0x82 \\
2014 SPECIAL(1, 7)& &0x73 \\
2015 \DWLNSadvancepc&LEB128(2)&0x2, 0x2 \\
2016 \DWLNEendsequence{} &&0x0, 0x1, 0x1 \\
2017 \end{longtable}
2018 \end{centering}
2019
2020
2021 Table \refersec{tab:linenumberprogramexamplealternateencoding}
2022 shows an alternate 
2023 encoding of the same program using 
2024 standard opcodes to advance
2025 the program counter; 
2026 this encoding occupies 22 bytes.
2027
2028 \begin{centering}
2029 \setlength{\extrarowheight}{0.1cm}
2030 \begin{longtable}{l|l|l}
2031   \caption{Line number program example: alternate encoding} 
2032   \label{tab:linenumberprogramexamplealternateencoding} \\
2033   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
2034 \endfirsthead
2035   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
2036 \endhead
2037   \hline \emph{Continued on next page}
2038 \endfoot
2039   \hline
2040 \endlastfoot
2041 \DWLNSfixedadvancepc&0x239&0x9, 0x39, 0x2        \\
2042 SPECIAL(2, 0)&& 0xb        \\
2043 \DWLNSfixedadvancepc&0x3&0x9, 0x3, 0x0        \\
2044 SPECIAL(2, 0)&&0xb        \\
2045 \DWLNSfixedadvancepc&0x8&0x9, 0x8, 0x0        \\
2046 SPECIAL(1, 0)&& 0xa        \\
2047 \DWLNSfixedadvancepc&0x7&0x9, 0x7, 0x0        \\
2048 SPECIAL(1, 0) && 0xa        \\
2049 \DWLNSfixedadvancepc&0x2&0x9, 0x2, 0x0        \\
2050 \DWLNEendsequence&&0x0, 0x1, 0x1        \\
2051 \end{longtable}
2052 \end{centering}
2053
2054 \needlines{6}
2055 \section{Call Frame Information Example}
2056 \label{app:callframeinformationexample}
2057
2058 The following example uses a hypothetical RISC machine in
2059 the style of the Motorola 88000.
2060 \begin{itemize}
2061 \item Memory is byte addressed.
2062
2063 \item Instructions are all 4 bytes each and word aligned.
2064
2065 \item Instruction operands are typically of the form:
2066 \begin{alltt}
2067     <destination.reg>, <source.reg>, <constant>
2068 \end{alltt}
2069
2070 \item The address for the load and store instructions is computed
2071 by adding the contents of the
2072 source register with the constant.
2073
2074 \item There are eight 4-byte registers:
2075 \newline
2076 \begin{tabular}{p{5mm}l}
2077    & R0 always 0 \\
2078    & R1 holds return address on call \\
2079    & R2-R3 temp registers (not preserved on call) \\
2080    & R4-R6 preserved on call \\
2081    & R7 stack pointer \\
2082 \end{tabular}
2083
2084 \item  The stack grows in the negative direction.
2085
2086 \item The architectural ABI committee specifies that the
2087 stack pointer (R7) is the same as the CFA
2088
2089 \end{itemize}
2090
2091 Figure \referfol{fig:callframeinformationexamplemachinecodefragments}
2092 shows two code fragments from a subroutine called
2093 foo that uses a frame pointer (in addition to the stack
2094 pointer). The first column values are byte addresses. 
2095 % The \space is so we get a space after >
2096 \textless fs\textgreater\ denotes the stack frame size in bytes, namely 12.
2097
2098
2099 \begin{figure}[h]
2100 \begin{lstlisting}
2101        ;; start prologue
2102 foo    sub   R7, R7, <fs>        ; Allocate frame
2103 foo+4  store R1, R7, (<fs>-4)    ; Save the return address
2104 foo+8  store R6, R7, (<fs>-8)    ; Save R6
2105 foo+12 add   R6, R7, 0           ; R6 is now the Frame ptr
2106 foo+16 store R4, R6, (<fs>-12)   ; Save a preserved reg
2107        ;; This subroutine does not change R5
2108        ...
2109        ;; Start epilogue (R7 is returned to entry value)
2110 foo+64 load  R4, R6, (<fs>-12)   ; Restore R4
2111 foo+68 load  R6, R7, (<fs>-8)    ; Restore R6
2112 foo+72 load  R1, R7, (<fs>-4)    ; Restore return address
2113 foo+76 add   R7, R7, <fs>        ; Deallocate frame
2114 foo+80 jump  R1                  ; Return
2115 foo+84
2116 \end{lstlisting}
2117 \caption{Call frame information example: machine code fragments}
2118 \label{fig:callframeinformationexamplemachinecodefragments}
2119 \end{figure}
2120
2121
2122 An abstract table 
2123 (see Section \refersec{chap:structureofcallframeinformation}) 
2124 for the foo subroutine is shown in 
2125 Table \referfol{tab:callframeinformationexampleconceptualmatrix}.
2126 Corresponding fragments from the
2127 \dotdebugframe{} section are shown in 
2128 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
2129
2130 The following notations apply in 
2131 Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
2132 \newline
2133 \begin{tabular}{p{5mm}l}
2134 &1.  R8 is the return address \\
2135 &2.  s = same\_value rule \\
2136 &3.  u = undefined rule \\
2137 &4.  rN = register(N) rule \\
2138 &5.  cN = offset(N) rule \\
2139 &6.  a = architectural rule \\
2140 \end{tabular}
2141
2142 \begin{centering}
2143 \setlength{\extrarowheight}{0.1cm}
2144 \begin{longtable}{l|llllllllll}
2145   \caption{Call frame information example: conceptual matrix} 
2146   \label{tab:callframeinformationexampleconceptualmatrix} \\
2147   \hline \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
2148 \endfirsthead
2149   \bfseries Location &\bfseries CFA &\bfseries R0 & \bfseries R1 & \bfseries R2 &\bfseries R3 &\bfseries R4 &\bfseries R5 &\bfseries R6 &\bfseries R7 &\bfseries R8\\ \hline
2150 \endhead
2151   \hline \emph{Continued on next page}
2152 \endfoot
2153   \hline
2154 \endlastfoot
2155 foo&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
2156 foo+4&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
2157 foo+8&[R7]+fs&s&u&u&u&s&s&s&a&c-4 \\
2158 foo+12&[R7]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
2159 foo+16&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
2160 foo+20&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
2161 ...&&&&&&&&&& \\
2162 foo+64&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
2163 foo+68&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4  \\
2164 foo+72&[R7]+fs&s&u&u&u&s&s&s&a&c-4  \\
2165 foo+76&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
2166 foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
2167 \end{longtable}
2168 \end{centering}
2169
2170 \clearpage      % ?????
2171
2172 \begin{centering}
2173 \setlength{\extrarowheight}{0.1cm}
2174 \begin{longtable}{l|ll}
2175   \caption{Call frame information example: common information entry encoding} 
2176   \label{tab:callframeinformationexamplecommoninformationentryencoding} 
2177   \\
2178   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
2179 \endfirsthead
2180   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
2181 \endhead
2182   \hline \emph{Continued on next page}
2183 \endfoot
2184   \hline
2185 \endlastfoot
2186 cie&36&length    \\
2187 cie+4&\xffffffff&CIE\_id    \\
2188 cie+8&4&version    \\
2189 cie+9&0&augmentation     \\
2190 cie+10&4&address size    \\
2191 cie+11&0&segment size    \\
2192 cie+12&4&code\_alignment\_factor, \textless caf \textgreater    \\
2193 cie+13&-4&data\_alignment\_factor, \textless daf \textgreater    \\
2194 cie+14&8&R8 is the return addr.    \\
2195 cie+15&\DWCFAdefcfa{} (7, 0)&CFA = [R7]+0    \\
2196 cie+18&\DWCFAsamevalue{} (0)&R0 not modified (=0)    \\
2197 cie+20&\DWCFAundefined{} (1)&R1 scratch    \\
2198 cie+22&\DWCFAundefined{} (2)&R2 scratch    \\
2199 cie+24&\DWCFAundefined{} (3)&R3 scratch    \\
2200 cie+26&\DWCFAsamevalue{} (4)&R4 preserve    \\
2201 cie+28&\DWCFAsamevalue{} (5)&R5 preserve    \\
2202 cie+30&\DWCFAsamevalue{} (6)&R6 preserve    \\
2203 cie+32&\DWCFAsamevalue{} (7)&R7 preserve    \\
2204 cie+34&\DWCFAregister{} (8, 1)&R8 is in R1    \\
2205 cie+37&\DWCFAnop{} &padding    \\
2206 cie+38&\DWCFAnop{} &padding \\
2207 cie+39& \DWCFAnop&padding  \\
2208 cie+40 &&  \\
2209 \end{longtable}
2210 \end{centering}
2211
2212
2213 The following notations apply in 
2214 Table \refersec{tab:callframeinformationexampleframedescriptionentryencoding}:
2215 \newline
2216 \begin{tabular}{p{5mm}l}
2217 &\texttt{<fs>  =} frame size \\
2218 &\texttt{<caf> =} code alignment factor \\
2219 &\texttt{<daf> =} data alignment factor \\
2220 \end{tabular}
2221
2222
2223 \begin{centering}
2224 \setlength{\extrarowheight}{0.1cm}
2225 \begin{longtable}{l|ll}
2226   \caption{Call frame information example: frame description entry encoding} 
2227   \label{tab:callframeinformationexampleframedescriptionentryencoding} \\
2228   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
2229 \endfirsthead
2230   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
2231 \endhead
2232   \hline \emph{Continued on next page}
2233 \endfoot
2234   \hline
2235 \endlastfoot
2236 fde&40&length \\
2237 fde+4&cie&CIE\_ptr \\
2238 fde+8&foo&initial\_location \\
2239 fde+12&84&address\_range \\
2240 fde+16&\DWCFAadvanceloc(1)&instructions \\
2241 fde+17&\DWCFAdefcfaoffset(12)& \textless fs\textgreater \\
2242 fde+19&\DWCFAadvanceloc(1)&4/\textless caf\textgreater \\
2243 fde+20&\DWCFAoffset(8,1)&-4/\textless daf\textgreater (2nd parameter) \\
2244 fde+22&\DWCFAadvanceloc(1)& \\
2245 fde+23&\DWCFAoffset(6,2)&-8/\textless daf\textgreater (2nd parameter)  \\
2246 fde+25&\DWCFAadvanceloc(1) & \\
2247 fde+26&\DWCFAdefcfaregister(6) & \\
2248 fde+28&\DWCFAadvanceloc(1) & \\
2249 fde+29&\DWCFAoffset(4,3)&-12/\textless daf\textgreater (2nd parameter) \\
2250 fde+31&\DWCFAadvanceloc(12)&44/\textless caf\textgreater \\
2251 fde+32&\DWCFArestore(4)& \\
2252 fde+33&\DWCFAadvanceloc(1) & \\
2253 fde+34&\DWCFArestore(6) & \\
2254 fde+35&\DWCFAdefcfaregister(7)  & \\
2255 fde+37&\DWCFAadvanceloc(1) & \\
2256 fde+38&\DWCFArestore(8) &\\
2257 fde+39&\DWCFAadvanceloc(1) &\\
2258 fde+40&\DWCFAdefcfaoffset(0)  &\\
2259 fde+42&\DWCFAnop&padding \\
2260 fde+43&\DWCFAnop&padding \\
2261 fde+44 && \\
2262 \end{longtable}
2263 \end{centering}
2264
2265 \needlines{6}
2266 \section{Inlining Examples}
2267 \label{app:inliningexamples}
2268 The pseudo\dash source in 
2269 Figure \referfol{fig:inliningexamplespseudosourcefragment}
2270 is used to illustrate the
2271 \addtoindexx{inlined subprogram call!examples}
2272 use of DWARF to describe inlined subroutine calls. This
2273 example involves a nested subprogram \texttt{INNER} that makes uplevel
2274 references to the formal parameter and local variable of the
2275 containing subprogram \texttt{OUTER}.
2276
2277 \begin{figure}[h]
2278 \begin{lstlisting}
2279 inline procedure OUTER (OUTER_FORMAL : integer) =
2280     begin
2281     OUTER_LOCAL : integer;
2282     procedure INNER (INNER_FORMAL : integer) =
2283         begin
2284         INNER_LOCAL : integer;
2285         print(INNER_FORMAL + OUTER_LOCAL);
2286         end;
2287     INNER(OUTER_LOCAL);
2288     ...
2289     INNER(31);
2290     end;
2291 ! Call OUTER
2292 !
2293 OUTER(7);
2294 \end{lstlisting}
2295 \caption{Inlining examples: pseudo-source fragmment} 
2296 \label{fig:inliningexamplespseudosourcefragment}
2297 \end{figure}
2298
2299
2300 There are several approaches that a compiler might take to
2301 inlining for this sort of example. This presentation considers
2302 three such approaches, all of which involve inline expansion
2303 of subprogram \texttt{OUTER}. (If \texttt{OUTER} is not inlined, the inlining
2304 reduces to a simpler single level subset of the two level
2305 approaches considered here.)
2306
2307 The approaches are:
2308 \begin{enumerate}[1. ]
2309 \item  Inline both \texttt{OUTER} and \texttt{INNER} in all cases
2310
2311 \item Inline \texttt{OUTER}, multiple \texttt{INNER}s \\
2312 Treat \texttt{INNER} as a non-inlinable part of \texttt{OUTER}, compile and
2313 call a distinct normal version of \texttt{INNER} defined within each
2314 inlining of \texttt{OUTER}.
2315
2316 \item Inline \texttt{OUTER}, one \texttt{INNER} \\
2317 Compile \texttt{INNER} as a single normal subprogram which is called
2318 from every inlining of \texttt{OUTER}.
2319 \end{enumerate}
2320
2321 This discussion does not consider why a compiler might choose
2322 one of these approaches; it considers only how to describe
2323 the result.
2324
2325 In the examples that follow in this section, the debugging
2326 information entries are given mnemonic labels of the following
2327 form
2328 \begin{verbatim}
2329     <io>.<ac>.<n>.<s>
2330 \end{verbatim}
2331 where
2332 \begin{description}
2333 \item[\textless io\textgreater]
2334 is either \texttt{INNER} or \texttt{OUTER} to indicate to which
2335 subprogram the debugging information entry applies, 
2336 \item[\textless ac\textgreater]
2337 is either AI or CI to indicate \doublequote{abstract instance} or
2338 \doublequote{concrete instance} respectively, 
2339 \item[\textless n\textgreater]
2340 is the number of the
2341 alternative being considered, and 
2342 \item[\textless s\textgreater]
2343 is a sequence number that
2344 distinguishes the individual entries. 
2345 \end{description}
2346 There is no implication
2347 that symbolic labels, nor any particular naming convention,
2348 are required in actual use.
2349
2350 For conciseness, declaration coordinates and call coordinates are omitted.
2351
2352 \subsection{Alternative \#1: inline both OUTER and INNER}
2353 \label{app:inlinebothouterandinner}
2354
2355 A suitable abstract instance for an alternative where both
2356 \texttt{OUTER} and \texttt{INNER} are always inlined is shown in 
2357 Figure \refersec{fig:inliningexample1abstractinstance}.
2358
2359 Notice in 
2360 Figure \ref{fig:inliningexample1abstractinstance} 
2361 that the debugging information entry for
2362 \texttt{INNER} (labelled \texttt{INNER.AI.1.1}) is nested in (is a child of)
2363 that for \texttt{OUTER} (labelled \texttt{OUTER.AI.1.1}). Nonetheless, the
2364 abstract instance tree for \texttt{INNER} is considered to be separate
2365 and distinct from that for \texttt{OUTER}.
2366
2367 The call of \texttt{OUTER} shown in 
2368 Figure \refersec{fig:inliningexamplespseudosourcefragment}
2369 might be described as
2370 shown in 
2371 Figure \refersec{fig:inliningexample1concreteinstance}.
2372
2373
2374 \begin{figure}[p]
2375 \begin{dwflisting}
2376 \begin{alltt}
2377     ! Abstract instance for OUTER
2378     ! \addtoindexx{abstract instance!example}
2379 OUTER.AI.1.1:
2380     \DWTAGsubprogram
2381         \DWATname("OUTER")
2382         \DWATinline(\DWINLdeclaredinlined)
2383         ! No low/high PCs
2384 OUTER.AI.1.2:
2385         \DWTAGformalparameter
2386             \DWATname("OUTER\_FORMAL")
2387             \DWATtype(reference to integer)
2388             ! No location
2389 OUTER.AI.1.3:
2390         \DWTAGvariable
2391             \DWATname("OUTER\_LOCAL")
2392             \DWATtype(reference to integer)
2393             ! No location
2394         !
2395         ! Abstract instance for INNER
2396         !
2397 INNER.AI.1.1:
2398         \DWTAGsubprogram
2399             \DWATname("INNER")
2400             \DWATinline(\DWINLdeclaredinlined)
2401             ! No low/high PCs
2402 INNER.AI.1.2:
2403             \DWTAGformalparameter
2404                 \DWATname("INNER\_FORMAL")
2405                 \DWATtype(reference to integer)
2406                 ! No location
2407 INNER.AI.1.3:
2408             \DWTAGvariable
2409                 \DWATname("INNER\_LOCAL")
2410                 \DWATtype(reference to integer)
2411                 ! No location
2412             ...
2413             0
2414         ! No \DWTAGinlinedsubroutine (concrete instance)
2415         ! for INNER corresponding to calls of INNER
2416         ...
2417         0
2418 \end{alltt}
2419 \end{dwflisting}
2420 \caption{Inlining example \#1: abstract instance}
2421 \label{fig:inliningexample1abstractinstance}
2422 \end{figure}
2423
2424 \begin{figure}[p]
2425 \begin{dwflisting}
2426 \begin{alltt}
2427 ! Concrete instance for call "OUTER(7)"
2428 ! \addtoindexx{concrete instance!example}
2429 OUTER.CI.1.1:
2430     \DWTAGinlinedsubroutine
2431         ! No name
2432         \DWATabstractorigin(reference to OUTER.AI.1.1)
2433         \DWATlowpc(...)
2434         \DWAThighpc(...)
2435 OUTER.CI.1.2:
2436         \DWTAGformalparameter
2437             ! No name
2438             \DWATabstractorigin(reference to OUTER.AI.1.2)
2439             \DWATconstvalue(7)
2440 OUTER.CI.1.3:
2441         \DWTAGvariable
2442             ! No name
2443             \DWATabstractorigin(reference to OUTER.AI.1.3)
2444             \DWATlocation(...)
2445         !
2446         ! No \DWTAGsubprogram (abstract instance) for INNER
2447         !
2448         ! Concrete instance for call INNER(OUTER\_LOCAL)
2449         !
2450 INNER.CI.1.1:
2451         \DWTAGinlinedsubroutine
2452             ! No name
2453             \DWATabstractorigin(reference to INNER.AI.1.1)
2454             \DWATlowpc(...)
2455             \DWAThighpc(...)
2456             \DWATstaticlink(...)
2457 INNER.CI.1.2:
2458             \DWTAGformalparameter
2459                 ! No name
2460                 \DWATabstractorigin(reference to INNER.AI.1.2)
2461                 \DWATlocation(...)
2462 INNER.CI.1.3:
2463             \DWTAGvariable
2464                 ! No name
2465                 \DWATabstractorigin(reference to INNER.AI.1.3)
2466                 \DWATlocation(...)
2467             ...
2468             0
2469         ! Another concrete instance of INNER within OUTER
2470         ! for the call "INNER(31)"
2471         ...
2472         0
2473 \end{alltt}
2474 \end{dwflisting}
2475 \caption{Inlining example \#1: concrete instance}
2476 \label{fig:inliningexample1concreteinstance}
2477 \end{figure}
2478
2479 \subsection{Alternative \#2: Inline OUTER, multiple INNERs}
2480 \label{app:inlineoutermultiipleinners}
2481
2482
2483 In the second alternative we assume that subprogram \texttt{INNER}
2484 is not inlinable for some reason, but subprogram \texttt{OUTER} is
2485 inlinable. 
2486 \addtoindexx{concrete instance!example}
2487 Each concrete inlined instance of \texttt{OUTER} has its
2488 own normal instance of \texttt{INNER}. 
2489 The abstract instance for \texttt{OUTER},
2490 \addtoindexx{abstract instance!example}
2491 which includes \texttt{INNER}, is shown in 
2492 Figure \refersec{fig:inliningexample2abstractinstance}.
2493
2494 Note that the debugging information in 
2495 Figure \ref{fig:inliningexample2abstractinstance}
2496 differs from that in 
2497 Figure \refersec{fig:inliningexample1abstractinstance}
2498 in that \texttt{INNER} lacks a 
2499 \DWATinline{} attribute
2500 and therefore is not a distinct abstract instance. \texttt{INNER}
2501 is merely an out\dash of\dash line routine that is part of \texttt{OUTER}\textquoteright s
2502 abstract instance. This is reflected in the Figure by
2503 \addtoindexx{abstract instance!example}
2504 the fact that the labels for \texttt{INNER} use the substring \texttt{OUTER}
2505 instead of \texttt{INNER}.
2506
2507 A resulting 
2508 \addtoindexx{concrete instance!example}
2509 concrete inlined instance of \texttt{OUTER} is shown in
2510 Figure \refersec{fig:inliningexample2concreteinstance}.
2511
2512 Notice in 
2513 Figure \ref{fig:inliningexample2concreteinstance}
2514 that \texttt{OUTER} is expanded as a concrete
2515 \addtoindexx{concrete instance!example}
2516 inlined instance, and that \texttt{INNER} is nested within it as a
2517 concrete out\dash of\dash line subprogram. Because \texttt{INNER} is cloned
2518 for each inline expansion of \texttt{OUTER}, only the invariant
2519 attributes of \texttt{INNER} 
2520 (for example, \DWATname) are specified
2521 in the abstract instance of \texttt{OUTER}, and the low\dash level,
2522 \addtoindexx{abstract instance!example}
2523 instance\dash specific attributes of \texttt{INNER} (for example,
2524 \DWATlowpc) are specified in 
2525 each concrete instance of \texttt{OUTER}.
2526 \addtoindexx{concrete instance!example}
2527
2528 The several calls of \texttt{INNER} within \texttt{OUTER} are compiled as normal
2529 calls to the instance of \texttt{INNER} that is specific to the same
2530 instance of \texttt{OUTER} that contains the calls.
2531
2532 \begin{figure}[t]
2533 \begin{dwflisting}
2534 \begin{alltt}
2535     ! Abstract instance for OUTER
2536     ! \addtoindex{abstract instance}
2537 OUTER.AI.2.1:
2538     \DWTAGsubprogram
2539         \DWATname("OUTER")
2540         \DWATinline(\DWINLdeclaredinlined)
2541         ! No low/high PCs
2542 OUTER.AI.2.2:
2543         \DWTAGformalparameter
2544             \DWATname("OUTER\_FORMAL")
2545             \DWATtype(reference to integer)
2546             ! No location
2547 OUTER.AI.2.3:
2548         \DWTAGvariable
2549             \DWATname("OUTER\_LOCAL")
2550             \DWATtype(reference to integer)
2551             ! No location
2552         !
2553         ! Nested out-of-line INNER subprogram
2554         !
2555 OUTER.AI.2.4:
2556         \DWTAGsubprogram
2557             \DWATname("INNER")
2558             ! No \DWATinline
2559             ! No low/high PCs, frame\_base, etc.
2560 OUTER.AI.2.5:
2561             \DWTAGformalparameter
2562                 \DWATname("INNER\_FORMAL")
2563                 \DWATtype(reference to integer)
2564                 ! No location
2565 OUTER.AI.2.6:
2566             \DWTAGvariable
2567                 \DWATname("INNER\_LOCAL")
2568                 \DWATtype(reference to integer)
2569                 ! No location
2570             ...
2571             0
2572         ...
2573         0
2574 \end{alltt}
2575 \end{dwflisting}
2576 \caption{Inlining example \#2: abstract instance}
2577 \label{fig:inliningexample2abstractinstance}
2578 \end{figure}
2579
2580 \begin{figure}[t]
2581 \begin{dwflisting}
2582 \begin{alltt}
2583
2584     ! Concrete instance for call "OUTER(7)"
2585     !
2586 OUTER.CI.2.1:
2587     \DWTAGinlinedsubroutine
2588         ! No name
2589         \DWATabstractorigin(reference to OUTER.AI.2.1)
2590         \DWATlowpc(...)
2591         \DWAThighpc(...)
2592 OUTER.CI.2.2:
2593         \DWTAGformalparameter
2594             ! No name
2595             \DWATabstractorigin(reference to OUTER.AI.2.2)
2596             \DWATlocation(...)
2597 OUTER.CI.2.3:
2598         \DWTAGvariable
2599             ! No name
2600             \DWATabstractorigin(reference to OUTER.AI.2.3)
2601             \DWATlocation(...)
2602         !
2603         ! Nested out-of-line INNER subprogram
2604         !
2605 OUTER.CI.2.4:
2606         \DWTAGsubprogram
2607             ! No name
2608             \DWATabstractorigin(reference to OUTER.AI.2.4)
2609             \DWATlowpc(...)
2610             \DWAThighpc(...)
2611             \DWATframebase(...)
2612             \DWATstaticlink(...)
2613 OUTER.CI.2.5:
2614             \DWTAGformalparameter
2615                 ! No name
2616                 \DWATabstractorigin(reference to OUTER.AI.2.5)
2617                 \DWATlocation(...)
2618 OUTER.CI.2.6:
2619             \DWTAGvariable
2620                 ! No name
2621                 \DWATabstractorigin(reference to OUTER.AT.2.6)
2622                 \DWATlocation(...)
2623             ...
2624             0
2625         ...
2626         0
2627 \end{alltt}
2628 \end{dwflisting}
2629 \caption{Inlining example \#2: concrete instance}
2630 \label{fig:inliningexample2concreteinstance}
2631 \end{figure}
2632
2633 \subsection{Alternative \#3: inline OUTER, one normal INNER}
2634 \label{app:inlineouteronenormalinner}
2635
2636 In the third approach, one normal subprogram for \texttt{INNER} is
2637 compiled which is called from all concrete inlined instances of
2638 \addtoindexx{concrete instance!example}
2639 \addtoindexx{abstract instance!example}
2640 \texttt{OUTER}. The abstract instance for \texttt{OUTER} is shown in 
2641 Figure \refersec{fig:inliningexample3abstractinstance}.
2642
2643 The most distinctive aspect of that Figure is that subprogram
2644 \texttt{INNER} exists only within the abstract instance of \texttt{OUTER},
2645 and not in \texttt{OUTER}\textquoteright s concrete instance. In the abstract
2646 \addtoindexx{concrete instance!example}
2647 \addtoindexx{abstract instance!example}
2648 instance of \texttt{OUTER}, the description of \texttt{INNER} has the full
2649 complement of attributes that would be expected for a
2650 normal subprogram. 
2651 While attributes such as 
2652 \DWATlowpc,
2653 \DWAThighpc, 
2654 \DWATlocation,
2655 and so on, typically are omitted
2656 \addtoindexx{high PC attribute}
2657 from 
2658 \addtoindexx{low PC attribute}
2659 an 
2660 \addtoindexx{location attribute}
2661 abstract instance because they are not invariant across
2662 instances of the containing abstract instance, in this case
2663 those same attributes are included precisely because they are
2664 invariant -- there is only one subprogram \texttt{INNER} to be described
2665 and every description is the same.
2666
2667 A concrete inlined instance of \texttt{OUTER} is illustrated in
2668 Figure \refersec{fig:inliningexample3concreteinstance}.
2669
2670 Notice in 
2671 Figure \ref{fig:inliningexample3concreteinstance}
2672 that there is no DWARF representation for
2673 \texttt{INNER} at all; the representation of \texttt{INNER} does not vary across
2674 instances of \texttt{OUTER} and the abstract instance of \texttt{OUTER} includes
2675 the complete description of \texttt{INNER}, so that the description of
2676 \texttt{INNER} may be (and for reasons of space efficiency, should be)
2677 omitted from each 
2678 \addtoindexx{concrete instance!example}
2679 concrete instance of \texttt{OUTER}.
2680
2681 There is one aspect of this approach that is problematical from
2682 the DWARF perspective. The single compiled instance of \texttt{INNER}
2683 is assumed to access up\dash level variables of \texttt{OUTER}; however,
2684 those variables may well occur at varying positions within
2685 the frames that contain the 
2686 \addtoindexx{concrete instance!example}
2687 concrete inlined instances. A
2688 compiler might implement this in several ways, including the
2689 use of additional compiler-generated parameters that provide
2690 reference parameters for the up\dash level variables, or a 
2691 compiler-generated static link like parameter that points to the group
2692 of up\dash level entities, among other possibilities. In either of
2693 these cases, the DWARF description for the location attribute
2694 of each uplevel variable needs to be different if accessed
2695 from within \texttt{INNER} compared to when accessed from within the
2696 instances of \texttt{OUTER}. An implementation is likely to require
2697 vendor\dash specific DWARF attributes and/or debugging information
2698 entries to describe such cases.
2699
2700 Note that in \addtoindex{C++}, a member function of a class defined within
2701 a function definition does not require any vendor\dash specific
2702 extensions because the \addtoindex{C++} language disallows access to
2703 entities that would give rise to this problem. (Neither \texttt{extern}
2704 variables nor \texttt{static} members require any form of static link
2705 for accessing purposes.)
2706
2707 \begin{figure}[t]
2708 \begin{dwflisting}
2709 \begin{alltt}
2710     ! Abstract instance for OUTER
2711     ! \addtoindexx{abstract instance!example}
2712 OUTER.AI.3.1:
2713     \DWTAGsubprogram
2714         \DWATname("OUTER")
2715         \DWATinline(\DWINLdeclaredinlined)
2716         ! No low/high PCs
2717 OUTER.AI.3.2:
2718         \DWTAGformalparameter
2719             \DWATname("OUTER\_FORMAL")
2720             \DWATtype(reference to integer)
2721             ! No location
2722 OUTER.AI.3.3:
2723         \DWTAGvariable
2724             \DWATname("OUTER\_LOCAL")
2725             \DWATtype(reference to integer)
2726             ! No location
2727         !
2728         ! Normal INNER
2729         !
2730 OUTER.AI.3.4:
2731         \DWTAGsubprogram
2732             \DWATname("INNER")
2733             \DWATlowpc(...)
2734             \DWAThighpc(...)
2735             \DWATframebase(...)
2736             \DWATstaticlink(...)
2737 OUTER.AI.3.5:
2738             \DWTAGformalparameter
2739                 \DWATname("INNER\_FORMAL")
2740                 \DWATtype(reference to integer)
2741                 \DWATlocation(...)
2742 OUTER.AI.3.6:
2743             \DWTAGvariable
2744                 \DWATname("INNER\_LOCAL")
2745                 \DWATtype(reference to integer)
2746                 \DWATlocation(...)
2747             ...
2748             0
2749         ...
2750         0
2751 \end{alltt}
2752 \end{dwflisting}
2753 \caption{Inlining example \#3: abstract instance}
2754 \label{fig:inliningexample3abstractinstance}
2755 \end{figure}
2756
2757 \begin{figure}[t]
2758 \begin{dwflisting}
2759 \begin{alltt}
2760     ! Concrete instance for call "OUTER(7)"
2761     ! \addtoindexx{concrete instance!example}
2762 OUTER.CI.3.1:
2763     \DWTAGinlinedsubroutine
2764         ! No name
2765         \DWATabstractorigin(reference to OUTER.AI.3.1)
2766         \DWATlowpc(...)
2767         \DWAThighpc(...)
2768         \DWATframebase(...)
2769 OUTER.CI.3.2:
2770         \DWTAGformalparameter
2771             ! No name
2772             \DWATabstractorigin(reference to OUTER.AI.3.2)
2773             ! No type
2774             \DWATlocation(...)
2775 OUTER.CI.3.3:
2776         \DWTAGvariable
2777             ! No name
2778             \DWATabstractorigin(reference to OUTER.AI.3.3)
2779             ! No type
2780             \DWATlocation(...)
2781         ! No \DWTAGsubprogram for "INNER"
2782         ...
2783         0
2784 \end{alltt}
2785 \end{dwflisting}
2786 \caption{Inlining example \#3: concrete instance}
2787 \label{fig:inliningexample3concreteinstance}
2788 \end{figure}
2789
2790 \clearpage
2791 \section{Constant Expression Example}
2792 \label{app:constantexpressionexample}
2793 \addtoindex{C++} generalizes the notion of constant expressions to include
2794 constant expression user-defined literals and functions.
2795 The constant declarations in Figure \refersec{fig:constantexpressionscsource}
2796 can be represented as illustrated in 
2797 Figure \refersec{fig:constantexpressionsdwarfdescription}.
2798
2799
2800 \begin{figure}[h]
2801 \begin{lstlisting}[numbers=none]
2802 constexpr double mass = 9.8;
2803 constexpr int square (int x) { return x * x; }
2804 float arr[square(9)]; // square() called and inlined
2805 \end{lstlisting}
2806 \caption{Constant expressions: C++ source} \label{fig:constantexpressionscsource}
2807 \end{figure}
2808
2809
2810 \begin{figure}[!h]
2811 \begin{dwflisting}
2812 \begin{alltt}
2813         ! For variable mass
2814         !
2815 1\$:     \DWTAGconsttype
2816             \DWATtype(reference to "double")
2817 2\$:     \DWTAGvariable
2818             \DWATname("mass")
2819             \DWATtype(reference to 1\$)
2820             \DWATconstexpr(true)
2821             \DWATconstvalue(9.8)
2822         ! Abstract instance for square
2823         !
2824 10\$:    \DWTAGsubprogram
2825             \DWATname("square")
2826             \DWATtype(reference to "int")
2827             \DWATinline(\DWINLinlined)
2828 11\$:        \DWTAGformalparameter
2829                 \DWATname("x")
2830                 \DWATtype(reference to "int")
2831         ! Concrete instance for square(9)
2832         ! \addtoindexx{concrete instance!example}
2833 20\$:    \DWTAGinlinedsubroutine
2834             \DWATabstractorigin(reference to 10\$)
2835             \DWATconstexpr(present)
2836             \DWATconstvalue(81)
2837             \DWTAGformalparameter
2838                 \DWATabstractorigin(reference to 11\$)
2839                 \DWATconstvalue(9)
2840         ! Anonymous array type for arr
2841         !
2842 30\$:    \DWTAGarraytype
2843             \DWATtype(reference to "float")
2844             \DWATbytesize(324) ! 81*4
2845             \DWTAGsubrangetype
2846                 \DWATtype(reference to "int")
2847                 \DWATupperbound(reference to 20\$)
2848         ! Variable arr
2849         !
2850 40\$:    \DWTAGvariable
2851             \DWATname("arr")
2852             \DWATtype(reference to 30\$)
2853 \end{alltt}
2854 \end{dwflisting}
2855 \caption{Constant expressions: DWARF description}
2856 \label{fig:constantexpressionsdwarfdescription}
2857 \end{figure}
2858
2859 \section{Unicode Character Example}
2860 \label{app:unicodecharacterexample}
2861 \addtoindexx{Unicode|see {\textit{also} UTF-8}}
2862 The \addtoindex{Unicode} character encodings in
2863 Figure \refersec{fig:unicodecharacterexamplesource}
2864 can be described in DWARF as illustrated in 
2865 Figure \refersec{fig:unicodecharacterexampledwarfdescription}.
2866
2867 \begin{figure}[!h]
2868 \begin{lstlisting}[numbers=none]
2869 // C++ source
2870 //
2871 char16_t chr_a = u'h';
2872 char32_t chr_b = U'h';
2873 \end{lstlisting}
2874 \caption{Unicode character example: source}
2875 \label{fig:unicodecharacterexamplesource}
2876 \end{figure}
2877
2878 \begin{figure}[h]
2879 \begin{dwflisting}
2880 \begin{alltt}
2881
2882 ! DWARF description
2883 !
2884 1\$: \DWTAGbasetype
2885         \DWATname("char16\_t")
2886         \DWATencoding(\DWATEUTF)
2887         \DWATbytesize(2)
2888 2\$: \DWTAGbasetype
2889         \DWATname("char32\_t")
2890         \DWATencoding(\DWATEUTF)
2891         \DWATbytesize(4)
2892 3\$: \DWTAGvariable
2893         \DWATname("chr\_a")
2894         \DWATtype(reference to 1\$)
2895 4\$: \DWTAGvariable
2896         \DWATname("chr\_b")
2897         \DWATtype(reference to 2\$)
2898 \end{alltt}
2899 \end{dwflisting}
2900 \caption{Unicode character example: DWARF description}
2901 \label{fig:unicodecharacterexampledwarfdescription}
2902 \end{figure}
2903
2904
2905 \section{Type-Safe Enumeration Example}
2906 \label{app:typesafeenumerationexample}
2907
2908 The \addtoindex{C++} type\dash safe enumerations in
2909 \addtoindexx{type-safe enumeration}
2910 Figure \refersec{fig:ctypesafeenumerationexamplesource}
2911 can be described in DWARF as illustrated in 
2912 Figure \refersec{fig:ctypesafeenumerationexampledwarf}.
2913
2914 \clearpage      % Get following source and DWARF on same page
2915
2916 \begin{figure}[H]
2917 \begin{lstlisting}[numbers=none]
2918 // C++ source
2919 //
2920 enum class E { E1, E2=100 };
2921 E e1;
2922 \end{lstlisting}
2923 \caption{Type-safe enumeration example: source}
2924 \label{fig:ctypesafeenumerationexamplesource}
2925 \end{figure}
2926
2927 \begin{figure}[H]
2928 \begin{dwflisting}
2929 \begin{alltt}
2930 ! DWARF description
2931 !
2932 11\$:  \DWTAGenumerationtype
2933           \DWATname("E")
2934           \DWATtype(reference to "int")
2935           \DWATenumclass(present)
2936 12\$:      \DWTAGenumerator
2937               \DWATname("E1")
2938               \DWATconstvalue(0)
2939 13\$:      \DWTAGenumerator
2940               \DWATname("E2")
2941               \DWATconstvalue(100)
2942 14\$:  \DWTAGvariable
2943          \DWATname("e1")
2944          \DWATtype(reference to 11\$)
2945 \end{alltt}
2946 \end{dwflisting}
2947 \caption{Type-safe enumeration example: DWARF description}
2948 \label{fig:ctypesafeenumerationexampledwarf}
2949 \end{figure}
2950
2951
2952 \clearpage
2953 \section{Template Examples}
2954 \label{app:templateexample}
2955
2956 The \addtoindex{C++} template example in
2957 Figure \refersec{fig:ctemplateexample1source}
2958 can be described in DWARF as illustrated in 
2959 Figure \refersec{fig:ctemplateexample1dwarf}.
2960
2961 \begin{figure}[h]
2962 \begin{lstlisting}
2963 // C++ source
2964 //
2965 template<class T>
2966 struct wrapper {
2967     T comp;
2968 };
2969 wrapper<int> obj;
2970 \end{lstlisting}
2971 \caption{C++ template example \#1: source}
2972 \label{fig:ctemplateexample1source}
2973 \end{figure}
2974
2975 \begin{figure}[h]
2976 \begin{dwflisting}
2977 \begin{alltt}
2978 ! DWARF description
2979 !
2980 11\$: \DWTAGstructuretype
2981         \DWATname("wrapper")
2982 12\$:    \DWTAGtemplatetypeparameter
2983             \DWATname("T")
2984             \DWATtype(reference to "int")
2985 13\$:    \DWTAGmember
2986             \DWATname("comp")
2987             \DWATtype(reference to 12\$)
2988 14\$: \DWTAGvariable
2989         \DWATname("obj")
2990         \DWATtype(reference to 11\$)
2991 \end{alltt}
2992 \end{dwflisting}
2993 \caption{C++ template example \#1: DWARF description}
2994 \label{fig:ctemplateexample1dwarf}
2995 \end{figure}
2996
2997 The actual type of the component \texttt{comp} is \texttt{int}, but in the DWARF
2998 the type references the
2999 \DWTAGtemplatetypeparameter{}
3000 for \texttt{T}, which in turn references \texttt{int}. This implies that in the
3001 original template comp was of type \texttt{T} and that was replaced
3002 with \texttt{int} in the instance. 
3003
3004 \needlines{10}
3005 There exist situations where it is
3006 not possible for the DWARF to imply anything about the nature
3007 of the original template. 
3008 Consider the \addtoindex{C++} template source in
3009 Figure \refersec{fig:ctemplateexample2source}
3010 and the DWARF that can describe it in
3011 Figure \refersec{fig:ctemplateexample2dwarf}.
3012
3013 \begin{figure}[!h]
3014 \begin{lstlisting}
3015 // C++ source
3016 //
3017     template<class T>
3018     struct wrapper {
3019         T comp;
3020     };
3021     template<class U>
3022     void consume(wrapper<U> formal)
3023     {
3024         ...
3025     }
3026     wrapper<int> obj;
3027     consume(obj);
3028 \end{lstlisting}
3029 \caption{C++ template example \#2: source}
3030 \label{fig:ctemplateexample2source}
3031 \end{figure}
3032
3033 \begin{figure}[h]
3034 \begin{dwflisting}
3035 \begin{alltt}
3036 ! DWARF description
3037 !
3038 11\$:  \DWTAGstructuretype
3039           \DWATname("wrapper")
3040 12\$:      \DWTAGtemplatetypeparameter
3041               \DWATname("T")
3042               \DWATtype(reference to "int")
3043 13\$:      \DWTAGmember
3044               \DWATname("comp")
3045               \DWATtype(reference to 12\$)
3046 14\$:  \DWTAGvariable
3047           \DWATname("obj")
3048           \DWATtype(reference to 11\$)
3049 21\$:  \DWTAGsubprogram
3050           \DWATname("consume")
3051 22\$:      \DWTAGtemplatetypeparameter
3052               \DWATname("U")
3053               \DWATtype(reference to "int")
3054 23\$:      \DWTAGformalparameter
3055               \DWATname("formal")
3056               \DWATtype(reference to 11\$)
3057 \end{alltt}
3058 \end{dwflisting}
3059 \caption{C++ template example \#2: DWARF description}
3060 \label{fig:ctemplateexample2dwarf}
3061 \end{figure}
3062
3063 In the \DWTAGsubprogram{} 
3064 entry for the instance of consume, \texttt{U} is described as \texttt{int}. 
3065 The type of formal is \texttt{wrapper\textless U\textgreater} in
3066 the source. DWARF only represents instantiations of templates;
3067 there is no entry which represents \texttt{wrapper\textless U\textgreater} 
3068 which is neither
3069 a template parameter nor a template instantiation. The type
3070 of formal is described as \texttt{wrapper\textless int\textgreater},
3071 the instantiation of \texttt{wrapper\textless U\textgreater},
3072 in the \DWATtype{} attribute at 
3073 23\$. 
3074 There is no
3075 description of the relationship between template type parameter
3076 \texttt{T} at 12\$ and \texttt{U} at 22\$ which was used to instantiate
3077 \texttt{wrapper\textless U\textgreater}.
3078
3079 A consequence of this is that the DWARF information would
3080 not distinguish between the existing example and one where
3081 the formal parameter of \texttt{consume} were declared in the source to be
3082 \texttt{wrapper\textless int\textgreater}.
3083
3084
3085 \section{Template Alias Examples}
3086 \label{app:templatealiasexample}
3087
3088 The \addtoindex{C++} template alias shown in
3089 Figure \refersec{fig:ctemplatealiasexample1source}
3090 can be described in DWARF as illustrated 
3091 \addtoindexx{template alias example} in 
3092 Figure \refersec{fig:ctemplatealiasexample1dwarf}.
3093
3094 \begin{figure}[h]
3095 \begin{lstlisting}
3096 // C++ source, template alias example 1
3097 //
3098 template<typename T, typename U>
3099 struct Alpha {
3100     T tango;
3101     U uniform;
3102 };
3103 template<typename V> using Beta = Alpha<V,V>;
3104 Beta<long> b;
3105 \end{lstlisting}
3106 \caption{C++ template alias example \#1: source}
3107 \label{fig:ctemplatealiasexample1source}
3108 \end{figure}
3109
3110 \begin{figure}[h]
3111 \addtoindexx{template alias example 1}
3112 \begin{dwflisting}
3113 \begin{alltt}
3114 ! DWARF representation for variable 'b'
3115 !
3116 20\$:  \DWTAGstructuretype
3117           \DWATname("Alpha")
3118 21\$:      \DWTAGtemplatetypeparameter
3119               \DWATname("T")
3120               \DWATtype(reference to "long")
3121 22\$:      \DWTAGtemplatetypeparameter
3122               \DWATname("U")
3123               \DWATtype(reference to "long")
3124 23\$:      \DWTAGmember
3125               \DWATname("tango")
3126               \DWATtype(reference to 21\$)
3127 24\$:      \DWTAGmember
3128               \DWATname("uniform")
3129               \DWATtype(reference to 22\$)
3130 25\$:  \DWTAGtemplatealias
3131           \DWATname("Beta")
3132           \DWATtype(reference to 20\$)
3133 26\$:      \DWTAGtemplatetypeparameter
3134               \DWATname("V")
3135               \DWATtype(reference to "long")
3136 27\$:  \DWTAGvariable
3137           \DWATname("b")
3138           \DWATtype(reference to 25\$)
3139 \end{alltt}
3140 \end{dwflisting}
3141 \caption{C++ template alias example \#1: DWARF description}
3142 \label{fig:ctemplatealiasexample1dwarf}
3143 \end{figure}
3144
3145 Similarly, the \addtoindex{C++} template alias shown in
3146 Figure \refersec{fig:ctemplatealiasexample2source}
3147 can be described in DWARF as illustrated 
3148 \addtoindexx{template alias example} in 
3149 Figure \refersec{fig:ctemplatealiasexample2dwarf}.
3150
3151 \begin{figure}[h]
3152 \begin{lstlisting}
3153 // C++ source, template alias example 2
3154 //
3155 template<class TX> struct X { };
3156 template<class TY> struct Y { };
3157 template<class T> using Z = Y<T>;
3158 X<Y<int>> y;
3159 X<Z<int>> z;
3160 \end{lstlisting}
3161 \caption{C++ template alias example \#2: source}
3162 \label{fig:ctemplatealiasexample2source}
3163 \end{figure}
3164
3165 \begin{figure}[h]
3166 \addtoindexx{template alias example 2}
3167 \begin{dwflisting}
3168 \begin{alltt}
3169 ! DWARF representation for X<Y<int>>
3170 !
3171 30\$:  \DWTAGstructuretype
3172           \DWATname("Y")
3173 31\$:      \DWTAGtemplatetypeparameter
3174               \DWATname("TY")
3175               \DWATtype(reference to "int")
3176 32\$:  \DWTAGstructuretype
3177           \DWATname("X")
3178 33\$:      \DWTAGtemplatetypeparameter
3179               \DWATname("TX")
3180               \DWATtype(reference to 30\$)
3181 !
3182 ! DWARF representation for X<Z<int>>
3183 !
3184 40\$:  \DWTAGtemplatealias
3185           \DWATname("Z")
3186           \DWATtype(reference to 30\$)
3187 41\$:      \DWTAGtemplatetypeparameter
3188               \DWATname("T")
3189               \DWATtype(reference to "int")
3190 42\$:  \DWTAGstructuretype
3191           \DWATname("X")
3192 43\$:      \DWTAGtemplatetypeparameter
3193               \DWATname("TX")
3194               \DWATtype(reference to 40\$)
3195 !
3196 ! Note that 32\$ and 42\$ are actually the same type
3197 !
3198 50\$:  \DWTAGvariable
3199           \DWATname("y")
3200           \DWATtype(reference to \$32)
3201 51\$:  \DWTAGvariable
3202           \DWATname("z")
3203           \DWATtype(reference to \$42)
3204 \end{alltt}
3205 \end{dwflisting}
3206 \caption{C++ template alias example \#2: DWARF description}
3207 \label{fig:ctemplatealiasexample2dwarf}
3208 \end{figure}
3209
3210 \clearpage
3211 \section{Implicit Pointer Examples}
3212 \label{app:implicitpointerexamples}
3213 If the compiler determines that the value of an object is
3214 constant (either throughout the program, or within a specific
3215 range), it may choose to materialize that constant only when
3216 used, rather than store it in memory or in a register. The
3217 \DWOPimplicitvalue{} operation can be used to describe such a
3218 value. Sometimes, the value may not be constant, but still can be
3219 easily rematerialized when needed. A DWARF expression terminating
3220 in \DWOPstackvalue{} can be used for this case. The compiler may
3221 also eliminate a pointer value where the target of the pointer
3222 resides in memory, and the \DWOPstackvalue{} operator may be used
3223 to rematerialize that pointer value. In other cases, the compiler
3224 will eliminate a pointer to an object that itself needs to be
3225 materialized. Since the location of such an object cannot be
3226 represented as a memory address, a DWARF expression cannot give
3227 either the location or the actual value or a pointer variable
3228 that would refer to that object. The \DWOPimplicitpointer{}
3229 operation can be used to describe the pointer, and the debugging
3230 information entry to which its first operand refers describes the
3231 value of the dereferenced object. A DWARF consumer will not be
3232 able to show the location or the value of the pointer variable,
3233 but it will be able to show the value of the dereferenced
3234 pointer.
3235
3236 Consider the \addtoindex{C} source shown in 
3237 Figure \refersec{fig:cimplicitpointerexample1source}.
3238 Assume that the function \texttt{foo} is not inlined,
3239 that the argument x is passed in register 5, and that the
3240 function \texttt{foo} is optimized by the compiler into just 
3241 an increment of the volatile variable \texttt{v}. Given these
3242 assumptions a possible DWARF description is shown in
3243 Figure \refersec{fig:cimplicitpointerexample1dwarf}.
3244
3245 \begin{figure}[h]
3246 \begin{lstlisting}
3247 struct S { short a; char b, c; };
3248 volatile int v;
3249 void foo (int x)
3250 {
3251     struct S s = { x, x + 2, x + 3 };
3252     char *p = &s.b;
3253     s.a++;
3254     v++;
3255 }
3256 int main ()
3257 {
3258     foo (v+1);
3259     return 0;
3260 }
3261 \end{lstlisting}
3262 \caption{C implicit pointer example \#1: source}
3263 \label{fig:cimplicitpointerexample1source}
3264 \end{figure}
3265
3266 \begin{figure}[h]
3267 \addtoindexx{implicit pointer example}
3268 \begin{dwflisting}
3269 \begin{alltt}
3270 1\$: \DWTAGstructuretype
3271         \DWATname("S")
3272         \DWATbytesize(4)
3273 10\$:    \DWTAGmember
3274             \DWATname("a")
3275             \DWATtype(reference to "short int")
3276             \DWATdatamemberlocation(constant 0)
3277 11\$:    \DWTAGmember
3278             \DWATname("b")
3279             \DWATtype(reference to "char")
3280             \DWATdatamemberlocation(constant 2)
3281 12\$:    \DWTAGmember
3282             \DWATname("c")
3283             \DWATtype(reference to "char")
3284             \DWATdatamemberlocation(constant 3)
3285 2\$: \DWTAGsubprogram
3286         \DWATname("foo")
3287 20\$:    \DWTAGformalparameter
3288             \DWATname("x")
3289             \DWATtype(reference to "int")
3290             \DWATlocation(\DWOPregfive)
3291 21\$:    \DWTAGvariable
3292             \DWATname("s")
3293             \DWATlocation(expression=
3294                 \DWOPbregfive(1) \DWOPstackvalue \DWOPpiece(2)
3295                 \DWOPbregfive(2) \DWOPstackvalue \DWOPpiece(1)
3296                 \DWOPbregfive(3) \DWOPstackvalue \DWOPpiece(1))
3297 22\$:    \DWTAGvariable
3298             \DWATname("p")
3299             \DWATtype(reference to "char *")
3300             \DWATlocation(expression=
3301                 \DWOPimplicitpointer(reference to 21\$, 2))
3302 \end{alltt}
3303 \end{dwflisting}
3304 \caption{C implicit pointer example \#1: DWARF description}
3305 \label{fig:cimplicitpointerexample1dwarf}
3306 \end{figure}
3307
3308 In Figure \refersec{fig:cimplicitpointerexample1dwarf},
3309 even though variables \texttt{s} and \texttt{p} are both optimized 
3310 away completely, this DWARF description still allows a debugger to 
3311 print the value of the variable \texttt{s}, namely \texttt{(2, 3, 4)}. 
3312 Similarly, because the variable \texttt{s} does not live in
3313 memory, there is nothing to print for the value of \texttt{p}, but the 
3314 debugger should still be able to show that \texttt{p[0]} is 3, 
3315 \texttt{p[1]} is 4, \texttt{p[-1]} is 0 and \texttt{p[-2]} is 2.
3316
3317 \needlines{6}
3318 As a further example, consider the C source 
3319 shown in Figure \refersec{fig:cimplicitpointerexample2source}. Make
3320 the following assumptions about how the code is compiled:
3321 \begin{itemize}
3322 \item The function \texttt{foo} is inlined
3323 into function \texttt{main}
3324 \item The body of the main function is optimized to just
3325 three blocks of instructions which each increment the volatile
3326 variable \texttt{v}, followed by a block of instructions to return 0 from
3327 the function
3328 \item Label \texttt{label0} is at the start of the main
3329 function, \texttt{label1} follows the first \texttt{v++} block, 
3330 \texttt{label2} follows the second \texttt{v++} block and 
3331 \texttt{label3} is at the end of the main function
3332 \item Variable \texttt{b} is optimized away completely, as it isn't used
3333 \item The string literal \texttt{"opq"} is optimized away as well
3334 \end{itemize}
3335 Given these assumptions a possible DWARF description is shown in
3336 Figure \refersec{fig:cimplicitpointerexample2dwarf}.
3337
3338 \begin{figure}[h]
3339 \begin{lstlisting}
3340 static const char *b = "opq";
3341 volatile int v;
3342 static inline void foo (int *p)
3343 {
3344     (*p)++;
3345     v++;
3346     p++;
3347     (*p)++;
3348     v++;
3349 }
3350 int main ()
3351 {
3352     int a[2] = { 1, 2 };
3353     v++;
3354     foo (a);
3355     return a[0] + a[1] - 5;
3356 }
3357 \end{lstlisting}
3358 \caption{C implicit pointer example \#2: source}
3359 \label{fig:cimplicitpointerexample2source}
3360 \end{figure}
3361
3362 \begin{figure}[h]
3363 \addtoindexx{implicit pointer example}
3364 \begin{dwflisting}
3365 \begin{alltt}
3366 1\$: \DWTAGvariable
3367         \DWATname("b")
3368         \DWATtype(reference to "const char *")
3369         \DWATlocation(expression=
3370             \DWOPimplicitpointer(reference to 2$, 0))
3371 2\$: \DWTAGdwarfprocedure
3372         \DWATlocation(expression=
3373             \DWOPimplicitvalue(4, \{'o', 'p', 'q', '\slash0'\}))
3374 3\$: \DWTAGsubprogram
3375         \DWATname("foo")
3376         \DWATinline(\DWINLdeclaredinlined)
3377 30\$:    \DWTAGformalparameter
3378             \DWATname("p")
3379             \DWATtype(reference to "int *")
3380 4\$: \DWTAGsubprogram
3381         \DWATname("main")
3382 40\$:           \DWTAGvariable
3383             \DWATname("a")
3384             \DWATtype(reference to "int[2]")
3385             \DWATlocation(location list 98$)
3386 41\$:    \DWTAGinlinedsubroutine
3387             \DWATabstractorigin(reference to 3$)
3388 42\$:        \DWTAGformalparameter
3389                 \DWATabstractorigin(reference to 30$)
3390                 \DWATlocation(location list 99$)
3391
3392 ! .debug_loc section
3393 98\$:<label0 in main> .. <label1 in main>
3394         \DWOPlitone \DWOPstackvalue \DWOPpiece(4)
3395         \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
3396     <label1 in main> .. <label2 in main>
3397         \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
3398         \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
3399     <label2 in main> .. <label3 in main>
3400         \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
3401         \DWOPlitthree \DWOPstackvalue \DWOPpiece(4)
3402     0 .. 0
3403 99\$:<label1 in main> .. <label2 in main>
3404         \DWOPimplicitpointer(reference to 40\$, 0)
3405     <label2 in main> .. <label3 in main>
3406         \DWOPimplicitpointer(reference to 40\$, 4)
3407     0 .. 0
3408 \end{alltt}
3409 \end{dwflisting}
3410 \caption{C implicit pointer example \#2: DWARF description}
3411 \label{fig:cimplicitpointerexample2dwarf}
3412 \end{figure}
3413
3414 \clearpage
3415 \section{String Type Examples}
3416 \label{app:stringtypeexamples}
3417 Consider the \addtoindex{Fortran 2003} string type example source in
3418 Figure \referfol{fig:stringtypeexamplesource}. The DWARF representation in
3419 Figure \refersec{fig:stringtypeexampledwarf} is appropriate.
3420
3421 \begin{figure}[h]
3422 \addtoindexx{ISO 10646 character set standard}
3423 \begin{lstlisting}
3424         program character_kind
3425             use iso_fortran_env
3426             implicit none
3427             integer, parameter :: ascii = 
3428                 selected_char_kind ("ascii")
3429             integer, parameter :: ucs4  = 
3430                 selected_char_kind ('ISO_10646')
3431             character(kind=ascii, len=26) :: alphabet
3432             character(kind=ucs4,  len=30) :: hello_world
3433             character (len=*), parameter :: all_digits="0123456789"
3434               
3435             alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
3436             hello_world = ucs4_'Hello World and Ni Hao -- ' &
3437                           // char (int (z'4F60'), ucs4)     &
3438                           // char (int (z'597D'), ucs4)
3439               
3440             write (*,*) alphabet
3441             write (*,*) all_digits
3442               
3443             open (output_unit, encoding='UTF-8')
3444             write (*,*) trim (hello_world)
3445         end program character_kind
3446 \end{lstlisting}
3447 \caption{String type example: source}
3448 \label{fig:stringtypeexamplesource}
3449 \end{figure}
3450
3451 \begin{figure}[h]
3452 \begin{dwflisting}
3453 \begin{alltt}
3454
3455 1\$: \DWTAGbasetype
3456         \DWATencoding (\DWATEASCII)
3457
3458 2\$: \DWTAGbasetype
3459         \DWATencoding (\DWATEUCS)
3460         \DWATbytesize (4)
3461
3462 3\$: \DWTAGstringtype
3463         \DWATbytesize (10)
3464
3465 4\$: \DWTAGconsttype
3466         \DWATtype (reference to 3\$)
3467       
3468 5\$: \DWTAGstringtype
3469         \DWATtype (1\$)
3470         \DWATstringlength ( ... )
3471         \DWATstringlengthbytesize ( ... )
3472         \DWATdatalocation ( ... )
3473       
3474 6\$: \DWTAGstringtype
3475         \DWATtype (2\$)
3476         \DWATstringlength ( ... )
3477         \DWATstringlengthbytesize ( ... )
3478         \DWATdatalocation ( ... )
3479
3480 7\$: \DWTAGvariable
3481         \DWATname (alphabet)
3482         \DWATtype (5\$)
3483         \DWATlocation ( ... )
3484
3485 8\$: \DWTAGconstant
3486         \DWATname (all\_digits)
3487         \DWATtype (4\$)
3488         \DWATconstvalue ( ... )
3489
3490 9\$: \DWTAGvariable
3491         \DWATname (hello\_world)
3492         \DWATtype (6\$)
3493         \DWATlocation ( ... )
3494         
3495 \end{alltt}
3496 \end{dwflisting}
3497 \caption{String type example: DWARF representation}
3498 \label{fig:stringtypeexampledwarf}
3499 \end{figure}
3500
3501 \clearpage
3502 \section{Call Site Examples}
3503 \label{app:callsiteexamples}
3504 The following examples use a hypothetical machine which: 
3505 \begin{itemize}
3506 \item
3507 Passes the first argument in register 0, the second in register 1, and the third in register 2.
3508 \item
3509 Keeps the stack pointer is register 3.
3510 \item
3511 Has one call preserved register 4.
3512 \item
3513 Returns a function value in register 0.
3514 \end{itemize}
3515
3516 \subsection{Call Site Example \#1 (C)}
3517 Consider the \addtoindex{C} source in Figure \referfol{fig:callsiteexample1source}.
3518
3519 \begin{figure}[h]
3520 \begin{lstlisting}
3521
3522 extern void fn1 (long int, long int, long int);
3523
3524 long int
3525 fn2 (long int a, long int b, long int c) 
3526 {
3527     long int q = 2 * a;
3528     fn1 (5, 6, 7); 
3529     return 0;
3530 }
3531  
3532 long int
3533 fn3 (long int x, long int (*fn4) (long int *))
3534 {
3535     long int v, w, w2, z;
3536     w = (*fn4) (&w2);
3537     v = (*fn4) (&w2);
3538     z = fn2 (1, v + 1, w);
3539     {
3540         int v1 = v + 4;
3541         z += fn2 (w, v * 2, x);
3542     }
3543     return z;
3544 }
3545 \end{lstlisting}
3546 \caption{Call Site Example \#1: Source}
3547 \label{fig:callsiteexample1source}
3548 \end{figure}
3549
3550 Possible generated code for this source is shown using a suggestive 
3551 pseudo-\linebreak[0]assembly notation in Figure \refersec{fig:callsiteexample1code}.
3552
3553 \begin{figure}[ht]
3554 \begin{lstlisting}
3555 fn2:
3556 L1:
3557     %reg2 = 7   ! Load the 3rd argument to fn1
3558     %reg1 = 6   ! Load the 2nd argument to fn1
3559     %reg0 = 5   ! Load the 1st argument to fn1
3560 L2:
3561     call fn1
3562     %reg0 = 0   ! Load the return value from the function
3563     return
3564 L3:
3565 fn3:
3566     ! Decrease stack pointer to reserve local stack frame
3567     %reg3 = %reg3 - 32
3568     [%reg3] = %reg4       ! Save the call preserved register to
3569                           !   stack
3570     [%reg3 + 8] = %reg0   ! Preserve the x argument value
3571     [%reg3 + 16] = %reg1  ! Preserve the fn4 argument value
3572     %reg0 = %reg3 + 24    ! Load address of w2 as argument
3573     call %reg1            ! Call fn4 (indirect call)
3574 L6:
3575     %reg2 = [%reg3 + 16]  ! Load the fn4 argument value
3576     [%reg3 + 16] = %reg0  ! Save the result of the first call (w)
3577     %reg0 = %reg3 + 24    ! Load address of w2 as argument
3578     call %reg2            ! Call fn4 (indirect call)
3579 L7:
3580     %reg4 = %reg0         ! Save the result of the second call (v) 
3581                           !   into register.
3582     %reg2 = [%reg3 + 16]  ! Load 3rd argument to fn2 (w)
3583     %reg1 = %reg4 + 1     ! Compute 2nd argument to fn2 (v + 1)
3584     %reg0 = 1             ! Load 1st argument to fn2
3585     call fn2
3586 L4:
3587     %reg2 = [%reg3 + 8]   ! Load the 3rd argument to fn2 (x)
3588     [%reg3 + 8] = %reg0   ! Save the result of the 3rd call (z)
3589     %reg0 = [%reg3 + 16]  ! Load the 1st argument to fn2 (w)
3590     %reg1 = %reg4 + %reg4 ! Compute the 2nd argument to fn2 (v * 2)
3591     call fn2
3592 L5:
3593     %reg2 = [%reg3 + 8]   ! Load the value of z from the stack
3594     %reg0 = %reg0 + %reg2 ! Add result from the 4th call to it
3595 L8:
3596     %reg4 = [%reg3]       ! Restore original value of call preserved 
3597                           !   register
3598     %reg3 = %reg3 + 32    ! Leave stack frame
3599     return
3600 \end{lstlisting}
3601 \caption{Call Site Example \#1: Code}
3602 \label{fig:callsiteexample1code}
3603 \end{figure}
3604
3605 \clearpage
3606 The location list for variable \texttt{a} in function \texttt{fn2}
3607 might look like:
3608 %\begin{figure}[h]
3609 \begin{lstlisting}
3610
3611 ! Before the call to fn1 the argument a is live in the register 0
3612 !
3613 <L1, L2> DW_OP_reg0
3614
3615 ! Afterwards it is not, the call could have clobbered the register,
3616 ! and it is not saved in the fn2 function stack frame either, but 
3617 ! perhaps can be looked up in the caller
3618 !
3619 <L2, L3> DW_OP_entry_value 1 DW_OP_reg0 DW_OP_stack_value
3620 <0, 0>
3621
3622 \end{lstlisting}
3623 %\end{figure}
3624 (where the notation \doublequote{\texttt{<m, n>}} specifies the address
3625 range over which the following location description applies).
3626
3627 Similarly, the variable q in fn2 then might have location list:
3628 \begin{lstlisting}
3629
3630 ! Before the call to fn1 the value of q can be computed as two times
3631 ! the value of register 0
3632 !
3633 <L1, L2> DW_OP_lit2 DW_OP_breg0 0 DW_OP_mul DW_OP_stack_value
3634
3635 ! Afterwards it can be computed from the original value of the first
3636 ! parameter, multiplied by two
3637 !
3638 <L2, L3> DW_OP_lit2 DW_OP_entry_value 1 DW_OP_reg0 DW_OP_mul DW_OP_stack_value
3639 <0, 0>
3640
3641 \end{lstlisting}
3642
3643 Variables \texttt{b} and \texttt{c} each have a location list similar to 
3644 that for variable \texttt{a},
3645 except for a different label between the two ranges and they
3646 use \DWOPregone{} and \DWOPregtwo{}, respectively, instead of \DWOPregzero.
3647
3648
3649 The call sites for all the calls in function \texttt{fn3} are children of the
3650 \DWTAGsubprogram{} entry for \texttt{fn3} (or of its \DWTAGlexicalblock{} entry
3651 if there is any for the whole function). 
3652 This is shown in Figure \refersec{fig:callsiteexample1dwarf}.
3653
3654 \begin{figure}[h]
3655 \figurepart{1}{2}
3656 \begin{dwflisting}
3657 \begin{alltt}
3658     \DWTAGcallsite
3659         \DWATcallreturnpc(L6) ! First indirect call to (*fn4) in fn3.
3660         ! The address of the call is preserved across the call in memory at
3661         ! stack pointer + 16 bytes.
3662         \DWATcalltarget(\DWOPbregthree{} 16 \DWOPderef)
3663         \DWTAGcallsiteparameter
3664             \DWATlocation(\DWOPregzero)
3665             ! Value of the first parameter is equal to stack pointer + 24 bytes.
3666             \DWATcallvalue(\DWOPbregthree{} 24)
3667     \DWTAGcallsite
3668         \DWATcallreturnpc(L7) ! Second indirect call to (*fn4) in fn3.
3669         ! The address of the call is not preserved across the call anywhere, but
3670         ! could be perhaps looked up in fn3's caller.
3671         \DWATcalltarget(\DWOPentryvalue{} 1 \DWOPregone)
3672         \DWTAGcallsiteparameter
3673             \DWATlocation(\DWOPregzero)
3674             \DWATcallvalue(\DWOPbregthree{} 24)
3675     \DWTAGcallsite
3676         \DWATcallreturnpc(L4) ! 3rd call in fn3, direct call to fn2
3677         \DWATcallorigin(reference to fn2 DW_TAG_subprogram)
3678         \DWTAGcallsiteparameter
3679             \DWATcallparameter(reference to formal parameter a in subprogram fn2)
3680             \DWATlocation(\DWOPregzero)
3681             ! First parameter to fn2 is constant 1
3682             \DWATcallvalue(\DWOPlitone)
3683         \DWTAGcallsiteparameter
3684             \DWATcallparameter(reference to formal parameter b in subprogram fn2)
3685             \DWATlocation(\DWOPregone)
3686             ! Second parameter to fn2 can be computed as the value of the call
3687             !   preserved register 4 in the fn3 function plus one
3688             \DWATcallvalue(\DWOPbregfour{} 1)
3689         \DWTAGcallsiteparameter
3690             \DWATcallparameter(reference to formal parameter c in subprogram fn2)
3691             \DWATlocation(\DWOPregtwo)
3692             ! Third parameter's value is preserved in memory at fn3's stack pointer
3693             !   plus 16 bytes
3694             \DWATcallvalue(\DWOPbregthree{} 16 \DWOPderef)
3695 \end{alltt}
3696 \end{dwflisting}
3697 \caption{Call site example \#1: DWARF encoding}
3698 \label{fig:callsiteexample1dwarf}
3699 \end{figure}
3700
3701 \begin{figure}
3702 \figurepart{2}{2}
3703 \begin{dwflisting}
3704 \begin{alltt}
3705 \DWTAGlexicalblock
3706     \DWATlowpc(L4)
3707     \DWAThighpc(L8)
3708     \DWTAGvariable
3709         \DWATname("v1")
3710         \DWATtype(reference to int)
3711         ! Value of the v1 variable can be computed as value of register 4 plus 4
3712         \DWATlocation(\DWOPbregfour{} 4 \DWOPstackvalue)
3713     \DWTAGcallsite
3714         \DWATcallreturnpc(L5) ! 4th call in fn3, direct call to fn2
3715         \DWATcalltarget(reference to subprogram fn2)
3716         \DWTAGcallsiteparameter
3717             \DWATcallparameter(reference to formal parameter a in subprogram fn2)
3718             \DWATlocation(\DWOPregzero)
3719             ! Value of the 1st argument is preserved in memory at fn3's stack 
3720             !   pointer + 16 bytes.
3721             \DWATcallvalue(\DWOPbregthree{} 16 \DWOPderef)
3722         \DWTAGcallsiteparameter
3723             \DWATcallparameter(reference to formal parameter b in subprogram fn2)
3724             \DWATlocation(\DWOPregone)
3725             ! Value of the 2nd argument can be computed using the preserved 
3726             !   register 4 multiplied by 2
3727             \DWATcallvalue(\DWOPlittwo{} \DWOPregfour{} 0 \DWOPmul)
3728         \DWTAGcallsiteparameter
3729             \DWATcallparameter(reference to formal parameter c in subprogram fn2)
3730             \DWATlocation(\DWOPregtwo)
3731             ! Value of the 3rd argument is not preserved, but could be perhaps 
3732             ! computed from the value passed fn3's caller.
3733             \DWATcallvalue(\DWOPentryvalue{} 1 \DWOPregzero)
3734 \end{alltt}
3735 \end{dwflisting}
3736 \begin{center}
3737 \vspace{3mm}
3738 Figure~\ref{fig:callsiteexample1dwarf} Call site example \#1: DWARF encoding \textit{(concluded)}
3739 \end{center}
3740 \end{figure}
3741
3742 \clearpage
3743 \subsection{Call Site Example \#2 (Fortran)}
3744 Consider the \addtoindex{Fortran} source in 
3745 Figure \refersec{fig:callsiteexample2source}
3746 which is used to illustrate how Fortran's \doublequote{pass by reference}
3747 parameters can be handled.
3748
3749 \begin{figure}[h]
3750 \begin{lstlisting}
3751 subroutine fn4 (n)
3752     integer :: n, x
3753     x = n
3754     n = n / 2
3755     call fn6
3756 end subroutine
3757 subroutine fn5 (n)
3758     interface fn4
3759         subroutine fn4 (n)
3760             integer :: n
3761         end subroutine
3762     end interface fn4
3763     integer :: n, x
3764     call fn4 (n)
3765     x = 5
3766     call fn4 (x)
3767 end subroutine fn5
3768 \end{lstlisting}
3769 \caption{Call site example \#2: source}
3770 \label{fig:callsiteexample2source}
3771 \end{figure}
3772
3773 Possible generated code for this source is shown using a suggestive 
3774 pseudo-\linebreak[0]assembly notation in Figure \refersec{fig:callsiteexample2code}.
3775 \begin{figure}[h]
3776 \begin{lstlisting}
3777
3778 fn4:
3779     %reg2 = [%reg0]   ! Load value of n (passed by reference)
3780     %reg2 = %reg2 / 2 ! Divide by 2
3781     [%reg0] = %reg2   ! Update value of n
3782     call fn6          ! Call some other function
3783     return
3784
3785 fn5:
3786     %reg3 = %reg3 - 8 ! Decrease stack pointer to create stack frame
3787     call fn4          ! Call fn4 with the same argument by reference 
3788                       !   as fn5 has been called with
3789 L9:
3790     [%reg3] = 5       ! Pass value of 5 by reference to fn4
3791     %reg0 = %reg3     ! Put address of the value 5 on the stack
3792                       !   into 1st argument register
3793     call fn4
3794 L10:
3795     %reg3 = %reg3 + 8 ! Leave stack frame
3796     return
3797     
3798 \end{lstlisting}
3799 \caption{Call site example \#2: code}
3800 \label{fig:callsiteexample2code}
3801 \end{figure}
3802
3803 The location description for variable \texttt{x} in function 
3804 \texttt{f}n4 might be:
3805 \begin{lstlisting}
3806 DW_OP_entry_value 4 DW_OP_breg0 0 DW_OP_deref_size 4 DW_OP_stack_value
3807 \end{lstlisting}
3808
3809 The call sites in (just) function \texttt{fn5} might be as shown in 
3810 Figure \refersec{fig:callsiteexample2dwarf}.
3811
3812 \begin{figure}[h]
3813 \begin{dwflisting}
3814 \begin{alltt}
3815
3816 \DWTAGcallsite
3817     \DWATcallreturnpc(L9) ! First call to fn4
3818     \DWATcallorigin(reference to subprogram fn4)
3819     \DWTAGcallsiteparameter
3820         \DWATcallparameter(reference to formal parameter n in subprogram fn4)
3821         \DWATlocation(\DWOPregzero)
3822         ! The value of register 0 at the time of the call can be perhaps 
3823         !   looked up in fn5's caller
3824         \DWATcallvalue(\DWOPentryvalue{} 1 \DWOPregzero)
3825         ! DW_AT_call_data_location(DW_OP_push_object_address) ! left out, implicit
3826         ! And the actual value of the parameter can be also perhaps looked up in
3827         ! fn5's caller
3828         \DWATcalldatavalue(\DWOPentryvalue{} 4 \DWOPbregzero{} 0 \DWOPderefsize 4)
3829         
3830 \DWTAGcallsite
3831     \DWATcallreturnpc(L10) ! Second call to fn4
3832     \DWATcallorigin(reference to subprogram fn4)
3833     \DWTAGcallsiteparameter
3834         \DWATcallparameter(reference to formal parameter n in subprogram fn4)
3835         \DWATlocation(\DWOPregzero)
3836         ! The value of register 0 at the time of the call is equal to the stack
3837         ! pointer value in fn5
3838         \DWATcallvalue(\DWOPbregthree{} 0)
3839         ! DW_AT_call_data_location(DW_OP_push_object_address) ! left out, implicit
3840         ! And the value passed by reference is constant 5
3841         \DWATcalldatavalue(\DWOPlitfive)
3842         
3843 \end{alltt}
3844 \end{dwflisting}
3845 \caption{Call site example \#2: DWARF encoding}
3846 \label{fig:callsiteexample2dwarf}
3847 \end{figure}
3848
3849
3850 \clearpage
3851 \section{Macro Example}
3852 \label{macroexample}
3853 Consider the \addtoindex{C} source in Figure 
3854 \referfol{ref:macroexamplesource} which is used to illustrate the
3855 DWARF encoding of macro information (see Section \refersec{chap:macroinformation}).
3856
3857 \begin{figure}[h]
3858 \textit{File a.c}
3859 \begin{lstlisting}
3860 #include "a.h"
3861 #define FUNCTION_LIKE_MACRO(x) 4+x
3862 #include "b.h"
3863 \end{lstlisting}
3864 \vspace{7mm}
3865 \textit{File a.h}
3866 \begin{lstlisting}
3867 #define LONGER_MACRO 1
3868 #define B 2
3869 #include "b.h"
3870 #define B 3
3871 \end{lstlisting}
3872 \vspace{7mm}
3873 \textit{File b.h}
3874 \begin{lstlisting}
3875 #undef B
3876 #define D 3
3877 #define FUNCTION_LIKE_MACRO(x) 4+x
3878 \end{lstlisting}
3879 \caption{Macro example: source}
3880 \label{ref:macroexamplesource}
3881 \end{figure}
3882
3883 Two possible encodings are shown. The first, in 
3884 Figure \refersec{fig:macroexamplesimpledwarfencoding}, is perhaps the simplest
3885 possible encoding. It includes all macro information from the
3886 main source file (\texttt{a.c}) as well as its two included files
3887 (\texttt{a.h} and \texttt{b.h}) in a single macro unit. Further,
3888 all strings are included as immediate operands of the macro
3889 operators (that is, there is no string pooling). The size
3890 of the macro unit is 160 bytes.
3891
3892 The second encoding, in 
3893 Figure \refersec{fig:macroexampledsharablewarfencoding},
3894 saves space in two ways:
3895 \begin{enumerate}[1. ]
3896 \item Longer strings are pooled by storing them in the
3897 \dotdebugstr{} section where they can be referenced more than
3898 once.
3899
3900 \item Macro information entries contained in included files
3901 are represented as separate macro units which are then
3902 imported for each \texttt{\#include} directive.
3903
3904 \end{enumerate}
3905 The combined size of the three macro units and their referenced
3906 strings is 129 bytes.
3907
3908 \needlines{4}
3909 A number of observations are worth mentioning:
3910 \begin{itemize}
3911 \item
3912 Strings that are the same size as a reference or less are
3913 better represented as immediate operands. Strings longer
3914 than twice the size of a reference are better stored in the
3915 string table if there are at least two references.
3916
3917 \item
3918 There is a trade-off between the size of the macro information
3919 of a file and the number of times it is included when evaluating
3920 whether to create a separate macro unit. However, the amount
3921 of overhead (the size of a macro header) needed to represent a
3922 unit as well as the size of the operation to import a macro unit
3923 are both small.
3924
3925 \item
3926 A macro unit need not describe all of the macro information in
3927 a file. For example, in Figure \ref{fig:macroexampledsharablewarfencoding}
3928 the second macro unit (beginning at \texttt{i\$1h}) includes macros
3929 from just the first two lines of file \texttt{a.h}.
3930
3931 \item
3932 An implementation may be able to share macro units across object
3933 files (not shown in this example). To support this, it may be
3934 advantageous to create macro units in cases where they do not
3935 offer an advantage in a single compilation of itself.
3936
3937 \needlines{6}
3938 \item
3939 The header of a macro unit that contains a \DWMACROstartfile{}
3940 operation must include a reference to the compilation line number 
3941 header to allow interpretation of the file number operands in
3942 those commands. However, the presence of those offsets complicates
3943 or may preclude sharing across compilations.
3944
3945 \end{itemize}
3946
3947
3948 \begin{figure}
3949 \begin{dwflisting}
3950 \begin{alltt}
3951
3952 ! *** Section \dotdebugmacro{} contents
3953 ! Macro unit for "a.c"
3954 0$h:    Version:        5
3955         Flags:          2
3956             \HFNoffsetsizeflag: 0           ! 4-byte offsets
3957             \HFNdebuglineoffsetflag: 1     ! Line number offset present
3958             \HFNopcodeoperandstableflag: 0 ! No extensions
3959         Offset in \dotdebugline{} section: 0  ! Line number offset
3960 0$m:    \DWMACROstartfile, 0, 0     ! Implicit Line: 0, File: 0 "a.c"
3961         \DWMACROstartfile, 1, 1     ! #include Line: 1, File: 1 "a.h"
3962         \DWMACROdefine, 1, "LONGER\_MACRO 1"
3963                                       ! #define Line: 1, String: "LONGER\_MACRO 1"  
3964         \DWMACROdefine, 2, "B 2"     ! #define Line: 2, String: "B 2"  
3965         \DWMACROstartfile, 3, 2     ! #include Line: 3, File: 2 "b.h" 
3966         \DWMACROundef, 1, "B"        ! #undef Line: 1, String: "b" 
3967         \DWMACROdefine 2, "D 3"      ! #define Line: 2, String: "D 3"
3968         \DWMACROdefine, 3, "FUNCTION\_LIKE\_MACRO(x) 4+x"
3969                                       ! #define Line: 3, 
3970                                       !   String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
3971         \DWMACROendfile{}             ! End "b.h" -> back to "a.h"
3972         \DWMACROdefine, 4, "B 3"     ! #define Line: 4, String: "B 3"
3973         \DWMACROendfile{}             ! End "a.h" -> back to "a.c"
3974         \DWMACROdefine, 2, "FUNCTION\_LIKE\_MACRO(x) 4+x"
3975                                       ! #define Line: 2, 
3976                                       !   String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
3977         \DWMACROstartfile, 3, 2     ! #include Line: 3, File: 2 "b.h" 
3978         \DWMACROundef, 1, "B"        ! #undef Line: 1, String: "b" 
3979         \DWMACROdefine, 2, "D 3"     ! #define Line: 2, String: "D 3"
3980         \DWMACROdefine, 3, "FUNCTION\_LIKE\_MACRO(x) 4+x"
3981                                       ! #define Line: 3, 
3982                                       !   String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
3983         \DWMACROendfile{}             ! End "b.h" -> back to "a.c"
3984         \DWMACROendfile{}             ! End "a.c" -> back to ""
3985         0                             ! End macro unit
3986 \end{alltt}
3987 \end{dwflisting}
3988 \caption{Macro example: simple DWARF encoding}
3989 \label{fig:macroexamplesimpledwarfencoding}
3990 \end{figure}
3991
3992
3993 \begin{figure}
3994 \begin{dwflisting}
3995 \begin{alltt}
3996 ! *** Section \dotdebugmacro{} contents
3997 ! Macro unit for "a.c"
3998 0$h:    Version:        5
3999         Flags:          2
4000             \HFNoffsetsizeflag: 0           ! 4-byte offsets
4001             \HFNdebuglineoffsetflag: 1     ! Line number offset present
4002             \HFNopcodeoperandstableflag: 0 ! No extensions
4003         Offset in \dotdebugline{} section: 0  ! Line number offset
4004 0$m:    \DWMACROstartfile, 0, 0     ! Implicit Line: 0, File: 0 "a.c"
4005         \DWMACROstartfile, 1, 1     ! #include Line: 1, File: 1 "a.h"
4006         \DWMACROimport, i$1h         ! Import unit at i$1h (lines 1-2)
4007         \DWMACROstartfile, 3, 2     ! #include Line: 3, File: 2 "b.h" 
4008         \DWMACROimport, i$2h         ! Import unit i$2h (lines all)
4009         \DWMACROendfile{}             ! End "b.h" -> back to "a.h"
4010         \DWMACROdefine, 4, "B 3"     ! #define Line: 4, String: "B 3"
4011         \DWMACROendfile{}             ! End "a.h" -> back to "a.c"
4012         \DWMACROdefine, 2, s$1       ! #define Line: 3, 
4013                                       !   String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
4014         \DWMACROstartfile, 3, 2     ! #include Line: 3, File: 2 "b.h" 
4015         \DWMACROimport, i$2h         ! Import unit i$2h (lines all)
4016         \DWMACROendfile{}             ! End "b.h" -> back to "a.c"
4017         \DWMACROendfile{}             ! End "a.c" -> back to ""
4018         0                             ! End macro unit
4019 ! Macro unit for "a.h" lines 1-2
4020 i$1h:   Version:        5
4021         Flags:          0
4022             \HFNoffsetsizeflag: 0           ! 4-byte offsets
4023             \HFNdebuglineoffsetflag: 0     ! No line number offset
4024             \HFNopcodeoperandstableflag: 0 ! No extensions
4025 i$1m:   \DWMACROdefinestrp, 1, s$2  ! #define Line: 1, String: "LONGER\_MACRO 1"  
4026         \DWMACROdefine, 2, "B 2"     ! #define Line: 2, String: "B 2"  
4027         0                             ! End macro unit
4028 ! Macro unit for "b.h"
4029 i$2h:   Version:        5
4030         Flags:          0
4031             \HFNoffsetsizeflag: 0           ! 4-byte offsets
4032             \HFNdebuglineoffsetflag: 0     ! No line number offset
4033             \HFNopcodeoperandstableflag: 0 ! No extensions
4034 i$2m:   \DWMACROundef, 1, "B"        ! #undef Line: 1, String: "B" 
4035         \DWMACROdefine, 2, "D 3"     ! #define Line: 2, String: "D 3"
4036         \DWMACROdefinestrp, 3, s$1  ! #define Line: 3, 
4037                                       !   String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
4038         0                             ! End macro unit
4039 ! *** Section \dotdebugstr{} contents
4040 s$1:    String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
4041 s$2:    String: "LONGER\_MACRO 1"
4042 \end{alltt}
4043 \end{dwflisting}
4044 \caption{Macro example: sharable DWARF encoding}
4045 \label{fig:macroexampledsharablewarfencoding}
4046 \end{figure}