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