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