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