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