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