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