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