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