ac77afb0213d274c826d6b9db9a16238763ee1aa
[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
9 \section{ Compilation Units and Abbreviations Table Example}
10 \label{app:compilationunitsandabbreviationstableexample}
11
12
13 Figure \refersec{fig:compilationunitsandabbreviationstable}
14 depicts the relationship of the abbreviations tables contained
15 \addtoindexx{abbreviations table!example}
16 \addtoindexx{.debug\_abbrev example}
17 \addtoindexx{.debug\_info example}
18 in the \addtoindex{.debug\_abbrev}
19 section to the information contained in
20 the \addtoindex{.debug\_info}
21 section. Values are given in symbolic form,
22 where possible.
23
24 The figure corresponds to the following two trivial source files:
25
26 File myfile.c
27 \begin{lstlisting}[numbers=none]
28 typedef char* POINTER;
29 \end{lstlisting}
30 File myfile2.c
31 \begin{lstlisting}[numbers=none]
32 typedef char* strp;
33 \end{lstlisting}
34
35 % Ensures we get the following float out before we go on.
36 \clearpage
37 \begin{figure}[here]
38 %\centering
39 \begin{minipage}{0.4\textwidth}
40 \centering
41 Compilation Unit \#1: \addtoindex{.debug\_info}
42 \begin{framed}
43 \scriptsize
44 \begin{alltt}
45 \textit{length}
46 4
47 \textit{a1 (abbreviations table offset)}
48 4
49 \vspace{0.01cm}
50 \hrule
51 1
52 "myfile.c"
53 "Best Compiler Corp: Version 1.3"
54 "/home/mydir/src"
55 \livelink{chap:DWLANGC89}{DW\-\_LANG\-\_C89}
56 0x0
57 0x55
58 \livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}
59 0x0
60 \vspace{0.01cm}
61 \hrule
62 2
63 \doublequote{char}
64 \livelink{chap:DWATEunsignedchar}{DW\-\_ATE\-\_unsigned\-\_char}
65 1
66 \vspace{0.01cm}
67 \hrule
68 3
69 e1
70 \vspace{0.01cm}
71 \hrule
72 4
73 \doublequote{POINTER}
74 e2
75 \vspace{0.01cm}
76 \hrule
77 0
78 \end{alltt}
79 %
80 %
81 \end{framed}
82 Compilation Unit \#2: \addtoindex{.debug\_info}
83 \begin{framed}
84 \scriptsize
85 \begin{alltt}
86 \textit{length}
87 4
88 \textit{a1 (abbreviations table offset)}
89 4
90 \vspace{0.01cm}
91 \hrule
92 ...
93 \vspace{0.01cm}
94 \hrule
95 4
96 \doublequote{strp}
97 e2
98 \vspace{0.01cm}
99 \hrule
100 ...
101 \end{alltt}
102 %
103 %
104 \end{framed}
105 \end{minipage}
106 \hfill
107 \begin{minipage}{0.4\textwidth}
108 \centering
109 Abbreviation Table: \addtoindex{.debug\_abbrev}
110 \begin{framed}
111 \scriptsize
112 \begin{alltt}
113 \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
114 \livelink{chap:DWCHILDRENyes}{DW\-\_CHILDREN\-\_yes}
115 \livelink{chap:DWATname}{DW\-\_AT\-\_name}       \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string}
116 \livelink{chap:DWATproducer}{DW\-\_AT\-\_producer}   \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string}
117 \livelink{chap:DWATcompdir}{DW\-\_AT\-\_comp\-\_dir}   \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string}
118 \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language}   \livelink{chap:DWFORMdata1}{DW\-\_FORM\-\_data1}
119 \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}     \livelink{chap:DWFORMaddr}{DW\-\_FORM\-\_addr}
120 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}    \livelink{chap:DWFORMdata1}{DW\-\_FORM\-\_data1}
121 \livelink{chap:DWATstmtlist}{DW\-\_AT\-\_stmt\-\_list}  \livelink{chap:DWFORMindirect}{DW\-\_FORM\-\_indirect}
122 0                  0
123 \vspace{0.01cm}
124 \hrule
125 2
126 \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
127 \livelink{chap:DWCHILDRENno}{DW\-\_CHILDREN\-\_no}
128 \livelink{chap:DWATname}{DW\-\_AT\-\_name}       \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string}
129 \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding}   \livelink{chap:DWFORMdata1}{DW\-\_FORM\-\_data1}
130 \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}  \livelink{chap:DWFORMdata1}{DW\-\_FORM\-\_data1}
131 0
132 \vspace{0.01cm}
133 \hrule
134 3
135 \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}
136 \livelink{chap:DWCHILDRENno}{DW\-\_CHILDREN\-\_no}
137 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}       \livelink{chap:DWFORMref4}{DW\-\_FORM\-\_ref4}
138 0
139 \vspace{0.01cm}
140 \hrule
141 4
142 \livelink{chap:DWTAGtypedef}{DW\-\_TAG\-\_typedef}
143 \livelink{chap:DWCHILDRENno}{DW\-\_CHILDREN\-\_no}
144 \livelink{chap:DWATname}{DW\-\_AT\-\_name}      \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string}
145 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}      \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr}
146 0
147 \vspace{0.01cm}
148 \hrule
149 0
150 \end{alltt}
151 \end{framed}
152 \end{minipage}
153 \caption{Compilation units and abbreviations table} \label{fig:compilationunitsandabbreviationstable}
154 \end{figure}
155
156 % Ensures we get the above float out before we go on.
157 \clearpage
158
159 \section{Aggregate Examples}
160 \label{app:aggregateexamples}
161
162 The following examples illustrate how to represent some of
163 the more complicated forms of array and record aggregates
164 using DWARF.
165
166 \subsection{Fortran 90 Example}
167 \label{app:fortran90example}
168 Consider the \addtoindex{Fortran 90} source fragment in 
169 \addtoindexx{array type entry!examples}
170 Figure \referfol{fig:fortran90examplesourcefragment}.
171
172 \begin{figure}[here]
173 \begin{lstlisting}
174 type array_ptr
175 real :: myvar
176 real, dimension (:), pointer :: ap
177 end type array_ptr
178 type(array_ptr), allocatable, dimension(:) :: arrays
179 allocate(arrays(20))
180 do i = 1, 20
181 allocate(arrays(i)%ap(i+10))
182 end do
183 \end{lstlisting}
184 \caption{Fortran 90 example: source fragment} \label{fig:fortran90examplesourcefragment}
185 \end{figure}
186
187 For allocatable and pointer arrays, it is essentially required
188 by the \addtoindex{Fortran 90} semantics that each array consist of 
189 \addtoindexx{descriptor!array}
190 two
191 \addtoindexx{array!descriptor for}
192 parts, which we here call 1) the descriptor and 2) the raw
193 data. (A descriptor has often been called a dope vector in
194 other contexts, although it is often a structure of some kind
195 rather than a simple vector.) Because there are two parts,
196 and because the lifetime of the descriptor is necessarily
197 longer than and includes that of the raw data, there must be
198 an address somewhere in the descriptor that points to the
199 raw data when, in fact, there is some (that is, when 
200 the ``variable'' is allocated or associated).
201
202 For concreteness, suppose that a descriptor looks something
203 like the C structure in 
204 Figure \refersec{fig:fortran90exampledescriptorrepresentation}.
205 Note, however, that it is
206 a property of the design that 1) a debugger needs no builtin
207 knowledge of this structure and 2) there does not need to
208 be an explicit representation of this structure in the DWARF
209 input to the 
210 \addtoindexx{Fortran 90}
211 debugger.
212
213 \begin{figure}[here]
214 \begin{lstlisting}
215 struct desc {
216     long el_len; // Element length
217     void * base; // Address of raw data
218     int ptr_assoc : 1; // Pointer is associated flag
219     int ptr_alloc : 1; // Pointer is allocated flag
220     int num_dims  : 6; // Number of dimensions
221     struct dims_str { // For each dimension...  
222         long low_bound;
223         long upper_bound;
224         long stride;
225     } dims[63];
226 };
227 \end{lstlisting}
228 \caption{Fortran 90 example: descriptor representation}
229 \label{fig:fortran90exampledescriptorrepresentation}
230 \end{figure}
231
232
233 In practice, of course, a \doublequote{real} descriptor will have
234 dimension substructures only for as many dimensions as are
235 specified in the num\_dims component. Let us use the notation
236 \texttt{desc\textless n\textgreater}   
237 to indicate a specialization of the desc struct in
238 which \texttt{n} is the bound for the dims component as well as the
239 contents of the num\_dims component.
240
241 Because the arrays considered here come in two parts, it is
242 necessary to distinguish the parts carefully. In particular,
243 the \doublequote{address of the variable} or equivalently, the \doublequote{base
244 address of the object} \emph{always} refers to the descriptor. For
245 arrays that do not come in two parts, an implementation can
246 provide a descriptor anyway, thereby giving it two parts. (This
247 may be convenient for general runtime support unrelated to
248 debugging.) In this case the above vocabulary applies as
249 stated. Alternatively, an implementation can do without a
250 descriptor, in which case the \doublequote{address of the variable},
251 or equivalently the \doublequote{base address of the object}, refers
252 to the \doublequote{raw data} (the real data, the only thing around
253 that can be the object).
254
255 If an object has a descriptor, then the DWARF type for that
256 object will have a 
257 \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} 
258 attribute. If an object
259 does not have a descriptor, then usually the DWARF type for the
260 object will not have a 
261 \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}. 
262 (See the following
263 \addtoindex{Ada} example for a case where the type for an object without
264 a descriptor does have a 
265 \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} attribute. In
266 that case the object doubles as its own descriptor.)
267
268 The \addtoindex{Fortran 90} derived type array\_ptr can now be redescribed
269 in C\dash like terms that expose some of the representation as in
270
271 \begin{lstlisting}[numbers=none]
272 struct array_ptr {
273     float myvar;
274     desc<1> ap;
275 };
276 \end{lstlisting}
277
278 Similarly for variable arrays:
279 \begin{lstlisting}[numbers=none]
280 desc<1> arrays;
281 \end{lstlisting}
282
283 (Recall that \texttt{desc\textless 1\textgreater} 
284 indicates the 1\dash dimensional version of \texttt{desc}.)
285
286 \newpage
287 Finally, the following notation is useful:
288 \begin{enumerate}[1. ]
289 \item  sizeof(type): size in bytes of entities of the given type
290 \item offset(type, comp): offset in bytes of the comp component
291 within an entity of the given type
292 \end{enumerate}
293
294 The DWARF description is shown 
295 \addtoindexx{Fortran 90}
296 in Figure \refersec{fig:fortran90exampledwarfdescription}.
297
298 \begin{figure}[h]
299 \figurepart{1}{2}
300 \begin{dwflisting}
301 \begin{alltt}
302 ! Description for type of 'ap'
303 !
304 1\$: \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type}
305         ! No name, default (Fortran) ordering, default stride
306         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to REAL)
307         \livelink{chap:DWATassociated}{DW\-\_AT\-\_associated}(expression= ! Test 'ptr\_assoc' \nolink{flag}
308             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
309             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n == offset(ptr\_assoc)
310             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
311             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref}
312             \livelink{chap:DWOPlit1}{DW\-\_OP\-\_lit1} ! mask for 'ptr\_assoc' \nolink{flag}
313             \livelink{chap:DWOPand}{DW\-\_OP\-\_and})
314         \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}(expression= ! Get raw data address
315             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
316             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n == offset(base)
317             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
318             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref}) ! Type of index of array 'ap'
319 2\$: \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
320         ! No name, default stride
321         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
322         \livelink{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}(expression=
323             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
324             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n ==
325                          !  offset(desc, dims) +
326                          !  offset(dims\_str, lower\_bound)
327             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
328             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref})
329         \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}(expression=
330             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
331             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n ==
332                          !  offset(desc, dims) +
333                          !  offset(dims\_str, upper\_bound)
334             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
335             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref})
336         !  Note: for the m'th dimension, the second operator becomes
337         !  \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<x> where
338         !       x == offset(desc, dims)         +
339         !                (m-1)*sizeof(dims\_str) +
340         !                 offset(dims\_str, [lower|upper]\_bound)
341         !  That is, the expression does not get longer for each successive 
342         !  dimension (other than to express the larger offsets involved).
343 \end{alltt}
344 \end{dwflisting}
345 \caption{Fortran 90 example: DWARF description}
346 \label{fig:fortran90exampledwarfdescription}
347 \end{figure}
348
349 \begin{figure}
350 \figurepart{2}{2}
351 \begin{dwflisting}
352 \begin{alltt}
353 3\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
354         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("array\_ptr")
355         \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}(constant sizeof(REAL) + sizeof(desc<1>))
356 4\$:     \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
357             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("myvar")
358             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to REAL)
359             \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location}(constant 0)
360 5\$:     \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
361             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("ap");
362             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
363             \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location}(constant sizeof(REAL))
364 6\$: \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type}
365         ! No name, default (Fortran) ordering, default stride
366         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 3\$)
367         \livelink{chap:DWATallocated}{DW\-\_AT\-\_allocated}(expression=
368             ! Test 'ptr\_alloc' \nolink{flag}
369             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
370             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n == offset(ptr\_alloc)
371             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
372             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref}
373             \livetarg{chap:DWOPlit2}{DW\-\_OP\-\_lit2}
374             ! Mask for 'ptr\_alloc' \nolink{flag}
375             \livelink{chap:DWOPand}{DW\-\_OP\-\_and})
376         \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}(expression= ! Get raw data address
377             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
378             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n = offset(base)
379             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
380             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref})
381 7\$: \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
382         ! No name, default stride
383         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
384         \livelink{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}(expression=
385             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
386             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n == ...
387             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
388             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref})
389         \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}(expression=
390             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
391             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n == ...
392             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
393             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref})
394 8\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
395         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("arrays")
396         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 6\$)
397         \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(expression=
398             ...as appropriate...) ! Assume static allocation
399 \end{alltt}
400 \end{dwflisting}
401 \begin{center}
402
403 Figure~\ref{fig:fortran90exampledwarfdescription} Fortran 90 example: DWARF description \textit{(concluded)}
404 \end{center}
405 \end{figure}
406
407 Suppose 
408 \addtoindexx{Fortran 90 example}
409 the program is stopped immediately following completion
410 of the do loop. Suppose further that the user enters the
411 following debug command:
412
413 \begin{lstlisting}[numbers=none]
414 debug> print arrays(5)%ap(2)
415 \end{lstlisting}
416
417 Interpretation of this expression proceeds as follows:
418 \begin{enumerate}[1. ]
419
420 \item Lookup name arrays. We find that it is a variable,
421 whose type is given by the unnamed type at 6\$. Notice that
422 the type is an array type.
423
424
425 \item Find the 5$^{th}$ element of that array object. To do array
426 indexing requires several pieces of information:
427 \begin{enumerate}[a) ]
428
429 \item  the address of the array data
430
431 \item the lower bounds of the array \\
432 % Using plain [] here gives trouble.
433 \lbrack To check that 5 is within bounds would require the upper
434 bound too, but we will skip that for this example. \rbrack
435
436 \item the stride 
437
438 \end{enumerate}
439
440 For a), check for a \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} attribute. Since
441 there is one, go execute the expression, whose result is
442 the address needed. The object address used in this case
443 is the object we are working on, namely the variable named
444 arrays , whose address was found in step 1. (Had there been
445 no \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} attribute, the desired address would
446 be the same as the address from step 1.)
447
448 For b), for each dimension of the array (only one
449 in this case), go interpret the usual lower bound
450 attribute. Again this is an expression, which again begins
451 with \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}. This object is 
452 \textbf{still} arrays,
453 from step 1, because we have not begun to actually perform
454 any indexing yet.
455
456 For c), the default stride applies. Since there is no
457 \livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride} attribute, use the size of the array element
458 type, which is the size of type array\_ptr (at 3\$).
459
460 \clearpage
461
462 Having acquired all the necessary data, perform the indexing
463 operation in the usual manner -  which has nothing to do with
464 any of the attributes involved up to now. Those just provide
465 the actual values used in the indexing step.
466
467 The result is an object within the memory that was dynamically
468 allocated for arrays.
469
470 \item  Find the ap component of the object just identified,
471 whose type is array\_ptr.
472
473 This is a conventional record component lookup and
474 interpretation. It happens that the ap component in this case
475 begins at offset 4 from the beginning of the containing object.
476 Component ap has the unnamed array type defined at 1\$ in the
477 symbol table.
478
479 \item  Find the second element of the array object found in step 3. To do array indexing requires
480 several pieces of information:
481 \begin{enumerate}[a) ]
482 \item  the address of the array storage
483
484 \item  the lower bounds of the array \\
485 % Using plain [] here gives trouble.
486 \lbrack To check that 2 is within bounds we would require the upper
487 bound too, but we will skip that for this example \rbrack
488
489 \item  the stride
490
491 \end{enumerate}
492 \end{enumerate}
493
494 This is just like step 2), so the details are omitted. Recall
495 that because the DWARF type 1\$ has a \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location},
496 the address that results from step 4) is that of a
497 descriptor, and that address is the address pushed by the
498 \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address} operations in 1\$ and 2\$.
499
500 Note: we happen to be accessing a pointer array here instead
501 of an allocatable array; but because there is a common
502 underlying representation, the mechanics are the same. There
503 could be completely different descriptor arrangements and the
504 mechanics would still be the same---only the stack machines
505 would be different.
506
507
508
509 \subsection{Ada Example}
510 \label{app:adaexample}
511
512 Figure \referfol{fig:adaexamplesourcefragment}
513 illustrates two kinds of \addtoindex{Ada} 
514 parameterized array, one embedded in a record.
515
516
517 \begin{figure}[here]
518 \begin{lstlisting}
519 M : INTEGER := <exp>;
520 VEC1 : array (1..M) of INTEGER;
521 subtype TEENY is INTEGER range 1..100;
522 type ARR is array (INTEGER range <>) of INTEGER;
523 type REC2(N : TEENY := 100) is record
524     VEC2 : ARR(1..N);
525 end record;
526
527 OBJ2B : REC2;
528 \end{lstlisting}
529 \caption{Ada 90 example: source fragment}
530 \label{fig:adaexamplesourcefragment}
531 \end{figure}
532
533 VEC1 illustrates an (unnamed) array type where the upper bound
534 of the first and only dimension is determined at runtime. 
535 \addtoindex{Ada}
536 semantics require that the value of an array bound is fixed at
537 the time the array type is elaborated (where elaboration refers
538 to the runtime executable aspects of type processing). For
539 the purposes of this example, we assume that there are no
540 other assignments to M so that it safe for the REC1 type
541 description to refer directly to that variable (rather than
542 a compiler generated copy).
543
544 REC2 illustrates another array type (the unnamed type of
545 component VEC2) where the upper bound of the first and only
546 bound is also determined at runtime. In this case, the upper
547 bound is contained in a discriminant of the containing record
548 type. (A discriminant is a component of a record whose value
549 cannot be changed independently of the rest of the record
550 because that value is potentially used in the specification
551 of other components of the record.)
552
553 The DWARF description is shown in 
554 Figure \refersec{fig:adaexampledwarfdescription}.
555
556
557 Interesting aspects about this example are:
558 \begin{enumerate}[1. ]
559 \item The array VEC2 is ``immediately'' contained within structure
560 REC2 (there is no intermediate descriptor or indirection),
561 which is reflected in the absence of a \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}
562 attribute on the array type at 28\$.
563
564 \item One of the bounds of VEC2 is nonetheless dynamic and part of
565 the same containing record. It is described as a reference to
566 a member, and the location of the upper bound is determined
567 as for any member. That is, the location is determined using
568 an address calculation relative to the base of the containing
569 object.  A consumer must notice that the referenced bound is a
570 member of the same containing object and implicitly push the
571 base address of the containing object just as for accessing
572 a data member generally.
573
574 \item The lack of a subtype concept in DWARF means that DWARF types
575 serve the role of subtypes and must replicate information from
576 what should be the parent type. For this reason, DWARF for
577 the unconstrained array ARR is not needed for the purposes
578 of this example and therefore not shown.
579 \end{enumerate}
580
581 \begin{figure}[p]
582 \begin{dwflisting}
583 \begin{alltt}
584 11\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
585         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("M")
586         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
587 12\$: \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type}
588         ! No name, default (\addtoindex{Ada}) order, default stride
589         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
590 13\$:    \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
591             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
592             \livelink{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}(constant 1)
593             \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}(reference to variable M at 11\$)
594 14\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
595         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("VEC1")
596         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to array type at 12\$)
597     . . .
598 21\$: \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
599         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("TEENY")
600         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
601         \livelink{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}(constant 1)
602         \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}(constant 100)
603
604       . . .
605 26\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
606         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("REC2")
607 27\$:    \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
608             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("N")
609             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to subtype TEENY at 21\$)
610             \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location}(constant 0)
611 28\$:   \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type}
612             ! No name, default (\addtoindex{Ada}) order, default stride
613             ! Default data location
614             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
615 29\$:        \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
616                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to subrange TEENY at 21\$)
617                 \livelink{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}(constant 1)
618                 \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}(reference to member N at 27\$)
619 30\$:   \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
620             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("VEC2")
621             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to array \doublequote{subtype} at 28\$)
622             \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location}(machine=
623                 \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n == offset(REC2, VEC2)
624                 \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus})
625       . . .
626 41\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
627         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OBJ2B")
628         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to REC2 at 26\$)
629         \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...as appropriate...)
630 \end{alltt}
631 \end{dwflisting}
632 \caption{Ada 90 example: DWARF description}
633 \label{fig:adaexampledwarfdescription}
634 \end{figure}
635
636 \subsection{Pascal Example}
637 \label{app:pascalexample}
638
639 The Pascal \addtoindexx{Pascal example} source in 
640 Figure \referfol{fig:packedrecordexamplesourcefragment}
641 is used to illustrate the representation of packed unaligned
642 \addtoindex{bit fields}.
643
644 \begin{figure}[here]
645 \begin{lstlisting}
646 TYPE T : PACKED RECORD                  ! bit size is 2
647          F5 : BOOLEAN;                  ! bit offset is 0
648          F6 : BOOLEAN;                  ! bit offset is 1
649          END;
650 VAR V  : PACKED RECORD
651          F1 : BOOLEAN;                  ! bit offset is 0
652          F2 : PACKED RECORD             ! bit offset is 1
653               F3 : INTEGER;             ! bit offset is 0 in F2, 1 in V
654               END;
655          F4 : PACKED ARRAY [0..1] OF T; ! bit offset is 33
656          F7 : T;                        ! bit offset is 37
657 END;
658 \end{lstlisting}
659 \caption{Packed record example: source fragment}
660 \label{fig:packedrecordexamplesourcefragment}
661 \end{figure}
662
663 The DWARF representation in 
664 Figure \refersec{fig:packedrecordexampledwarfdescription} 
665 is appropriate. 
666 \livelink{chap:DWTAGpackedtype}{DW\-\_TAG\-\_packed\-\_type} entries could be added to
667 better represent the source, but these do not otherwise affect
668 the example and are omitted for clarity. Note that this same
669 representation applies to both typical big\dash \ and 
670 little\dash endian
671 architectures using the conventions described in 
672 Section \refersec{chap:datamemberentries}.
673
674
675 \begin{figure}[p]
676 \begin{dwflisting}
677 % DWARF4 had some entries here as \livelink{chap:DWATmember}{DW_AT_member} .
678 % Those are fixed here to \livelink{chap:DWTAGmember}{DW_TAG_member}
679 \begin{alltt}
680
681 21\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type} ! anonymous type for F2
682         \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
683             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("F3")
684             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 11\$)
685 22\$: \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type} ! anonymous type for F4
686         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 20\$)
687         \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
688             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 11\$)
689             \livelink{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}(0)
690             \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}(1)
691         \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride}(2)
692         \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(4) \addtoindexx{bit size attribute}
693 23\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type} ! anonymous type for V
694         \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(39) \addtoindexx{bit size attribute}
695         \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
696             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("F1")
697             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 10\$)
698             \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}(0)! may be omitted
699             \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(1) ! may be omitted
700         \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
701             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("F2")
702             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 21\$)
703             \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}(1)
704             \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(32) ! may be omitted
705         \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
706             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("F4")
707             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 22\$)
708             \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}(33)
709             \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(4) ! may be omitted
710         \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
711             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("F7")
712             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 20\$) ! type T
713             \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}(37)
714             \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(2) \addtoindexx{bit size attribute}! may be omitted
715      \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
716         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("V")
717         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 23\$)
718         \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...)
719         ...
720 \end{alltt}
721 \end{dwflisting}
722 \caption{Packed record example: DWARF description}
723 \label{fig:packedrecordexampledwarfdescription}
724 \end{figure}
725
726 \section{Namespace Example}
727 \label{app:namespaceexample}
728
729 The \addtoindex{C++} example in 
730 Figure \refersec{fig:namespaceexamplesourcefragment}
731 is used 
732 \addtoindexx{namespace (C++)!example}
733 to illustrate the representation of namespaces.
734 The DWARF representation in 
735 Figure \refersec{fig:namespaceexampledwarfdescription}
736 is appropriate.
737
738 \begin{figure}[p]
739 \begin{lstlisting}
740 namespace {
741     int i;
742 }
743
744 namespace A {
745     namespace B {
746         int j;
747         int myfunc (int a);
748         float myfunc (float f) { return f \textendash 2.0; }
749         int myfunc2(int a) { return a + 2; }
750     }
751 }
752 namespace Y {
753     using A::B::j;         // (1) using declaration
754     int foo;
755 }
756
757 using A::B::j;             // (2) using declaration
758 namespace Foo = A::B;      // (3) namespace alias
759 using Foo::myfunc;         // (4) using declaration
760 using namespace Foo;       // (5) using directive
761 namespace A {
762     namespace B {
763         using namespace Y; // (6) using directive
764         int k;
765     }
766 }
767 int Foo::myfunc(int a)
768 {
769     i = 3;
770     j = 4;
771     return myfunc2(3) + j + i + a + 2;
772 }
773 \end{lstlisting}
774 \caption{Namespace example: source fragment}
775 \label{fig:namespaceexamplesourcefragment}
776 \end{figure}
777
778
779 \begin{figure}[p]
780 \begin{dwflisting}
781 \begin{alltt}
782
783 1\$:  \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
784         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("int")
785         ...
786 2\$:  \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
787         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("float")
788         ...
789 6\$:  \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}
790         ! no \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute
791 7\$:
792         \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
793             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("i")
794             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
795             \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} ...
796             ...
797 10\$: \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}
798         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("A")
799 20\$:    \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}
800             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("B")
801 30\$:        \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
802                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("j")
803                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
804                 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} ...
805                 ...
806 34\$:        \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
807                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("myfunc")
808                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
809                 ...
810 36\$:        \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
811                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("myfunc")
812                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 2\$)
813                 ...
814 38\$:        \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
815                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("myfunc2")
816                 \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} ...
817                 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} ...
818                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
819                 ...
820 \end{alltt}
821 \end{dwflisting}
822 \caption{Namespace example: DWARF description}
823 \label{fig:namespaceexampledwarfdescription}
824 \end{figure}
825
826 \begin{figure}
827 \begin{dwflisting}
828 \begin{alltt}
829 40\$: \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}
830         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("Y")
831         \livelink{chap:DWTAGimporteddeclaration}{DW\-\_TAG\-\_imported\-\_declaration}    ! (1) using-declaration
832             \livelink{chap:DWATimport}{DW\-\_AT\-\_import}(reference to 30\$)
833         \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
834             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("foo")
835             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
836             \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} ...
837             ...
838      \livelink{chap:DWTAGimporteddeclaration}{DW\-\_TAG\-\_imported\-\_declaration}       ! (2) using declaration
839         \livelink{chap:DWATimport}{DW\-\_AT\-\_import}(reference to 30\$)
840         \livelink{chap:DWTAGimporteddeclaration}{DW\-\_TAG\-\_imported\-\_declaration}    ! (3) namespace alias
841             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("Foo")
842             \livelink{chap:DWATimport}{DW\-\_AT\-\_import}(reference to 20\$)
843         \livelink{chap:DWTAGimporteddeclaration}{DW\-\_TAG\-\_imported\-\_declaration}    ! (4) using declaration
844             \livelink{chap:DWATimport}{DW\-\_AT\-\_import}(reference to 34\$) ! - part 1
845         \livelink{chap:DWTAGimporteddeclaration}{DW\-\_TAG\-\_imported\-\_declaration}    ! (4) using declaration
846             \livelink{chap:DWATimport}{DW\-\_AT\-\_import}(reference to 36\$) !  - part 2
847         \livelink{chap:DWTAGimportedmodule}{DW\-\_TAG\-\_imported\-\_module}         ! (5) using directive
848             \livelink{chap:DWATimport}{DW\-\_AT\-\_import}(reference to 20\$)
849         \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}
850             \livelink{chap:DWATextension}{DW\-\_AT\-\_extension}(reference to 10\$)
851             \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}
852                 \livelink{chap:DWATextension}{DW\-\_AT\-\_extension}(reference to 20\$)
853                 \livelink{chap:DWTAGimportedmodule}{DW\-\_TAG\-\_imported\-\_module} ! (6) using directive
854                     \livelink{chap:DWATimport}{DW\-\_AT\-\_import}(reference to 40\$)
855                 \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
856                     \livelink{chap:DWATname}{DW\-\_AT\-\_name}("k")
857                     \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
858                     \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} ...
859                     ...
860 60\$: \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
861         \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification}(reference to 34\$)
862         \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} ...
863         \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} ...
864         ...
865 \end{alltt}
866 \end{dwflisting}
867 \begin{center}
868 Figure~\ref{fig:namespaceexampledwarfdescription}: Namespace example: DWARF description \textit{(concluded)}
869 \end{center}
870 \end{figure}
871
872 \section{Member Function Example}
873 \label{app:memberfunctionexample}
874
875 Consider the member function example fragment in 
876 Figure \refersec{fig:memberfunctionexamplesourcefragment}.
877 The DWARF representation in 
878 Figure \refersec{fig:memberfunctionexampledwarfdescription}
879 is appropriate.
880
881 \begin{figure}[Here]
882 \begin{lstlisting}
883 class A
884 {
885     void func1(int x1);
886     void func2() const;
887     static void func3(int x3);
888 };
889 void A::func1(int x) {}
890 \end{lstlisting}
891 \caption{Member function example: source fragment}
892 \label{fig:memberfunctionexamplesourcefragment}
893 \end{figure}
894
895 \begin{figure}[h]
896 \begin{dwflisting}
897 \begin{alltt}
898 1\$: \livelink{chap:DWTAGunspecifiedtype}{DW\-\_TAG\-\_unspecified\-\_type}
899         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("void")
900                 ...
901 2\$ \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
902         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("int")
903         ...
904 3\$: \livelink{chap:DWTAGclasstype}{DW\-\_TAG\-\_class\-\_type}
905         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("A")
906         ...
907 4\$:    \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}
908             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 3\$)
909             ...
910 5\$:    \livelink{chap:DWTAGconsttype}{DW\-\_TAG\-\_const\-\_type}
911             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 3\$)
912             ...
913 6\$:    \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}
914             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 5\$)
915             ...
916
917 7\$:    \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
918             \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration}
919             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("func1")
920             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
921             \livelink{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer}(reference to 8\$) \addtoindexx{object pointer attribute}
922                 ! References a formal parameter in this 
923                 ! member function
924             ...
925 \end{alltt}
926 \end{dwflisting}
927 \caption{Member function example: DWARF description}
928 \label{fig:memberfunctionexampledwarfdescription}
929 \end{figure}
930
931 \begin{figure}[p]
932 \begin{dwflisting}
933 \begin{alltt}
934 8\$:        \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
935                 \livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial}(true)
936                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("this")
937                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 4\$)
938                     ! Makes type of 'this' as 'A*' =>
939                     ! func1 has not been marked const 
940                     ! or volatile
941                 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} ...
942                 ...
943 9\$:        \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
944                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}(x1)
945                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 2\$)
946                 ...
947 10\$:    \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
948              \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration}
949              \livelink{chap:DWATname}{DW\-\_AT\-\_name}("func2")
950              \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
951              \livelink{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer}(reference to 11\$) \addtoindexx{object pointer attribute}
952              ! References a formal parameter in this 
953              ! member function
954              ...
955 11\$:        \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
956                  \livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial}(true)
957                  \livelink{chap:DWATname}{DW\-\_AT\-\_name}("this")
958                  \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 6\$)
959                      ! Makes type of 'this' as 'A const*' =>
960                  !     func2 marked as const
961                  \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} ...
962                  ...
963 12\$:    \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
964              \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration}
965              \livelink{chap:DWATname}{DW\-\_AT\-\_name}("func3")
966              \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
967              ...
968                  ! No object pointer reference formal parameter
969                  ! implies func3 is static
970 13\$:        \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
971                  \livelink{chap:DWATname}{DW\-\_AT\-\_name}(x3)
972                  \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 2\$)
973                  ...
974 \end{alltt}
975 \end{dwflisting}
976 \begin{center}
977 Figure~\ref{fig:memberfunctionexampledwarfdescription}: Member function example: DWARF description \textit{(concluded)}
978 \end{center}
979 \end{figure}
980
981 \clearpage
982 \section{Line Number Program Example}
983 \label{app:linenumberprogramexample}
984
985 Consider the simple source file and the resulting machine
986 code for the Intel 8086 processor in 
987 Figure \refersec{fig:linenumberprogramexamplemachinecode}.
988
989 \begin{figure}[here]
990 \begin{lstlisting}
991 1: int
992 2: main()
993     0x239: push pb
994     0x23a: mov bp,sp
995 3: {
996 4: printf("Omit needless words\n");
997     0x23c: mov ax,0xaa
998     0x23f: push ax
999     0x240: call _printf
1000     0x243: pop cx
1001 5: exit(0);
1002     0x244: xor ax,ax
1003     0x246: push ax
1004     0x247: call _exit
1005     0x24a: pop cx
1006 6: }
1007     0x24b: pop bp
1008     0x24c: ret
1009 7: 0x24d:
1010 \end{lstlisting}
1011 \caption{Line number program example: machine code}
1012 \label{fig:linenumberprogramexamplemachinecode}
1013 \end{figure}
1014
1015 Suppose the line number program header includes the following
1016 (header fields not needed 
1017 \addtoindexx{line\_base}
1018 below 
1019 \addtoindexx{line\_range}
1020 are 
1021 \addtoindexx{opcode\_base}
1022 not 
1023 \addtoindexx{minumum\_instruction\_length}
1024 shown):
1025 \begin{alltt}
1026     version                       4
1027     minimum_instruction_length    1
1028     opcode_base                  10   ! Opcodes 10-12 not needed
1029     line_base                     1
1030     line_range                   15
1031 \end{alltt}
1032
1033
1034 Table \refersec{tab:linenumberprogramexampleoneencoding}
1035 shows one encoding of the line number program, which occupies
1036 12 bytes (the opcode SPECIAL(m,n) indicates the special opcode
1037 generated for a line increment of m and an address increment
1038 of n).
1039
1040 \newpage
1041 \begin{centering}
1042 \setlength{\extrarowheight}{0.1cm}
1043 \begin{longtable}{l|l|l}
1044   \caption{Line number program example: one encoding}
1045   \label{tab:linenumberprogramexampleoneencoding} \\
1046   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
1047 \endfirsthead
1048   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
1049 \endhead
1050   \hline \emph{Continued on next page}
1051 \endfoot
1052   \hline
1053 \endlastfoot
1054 \livelink{chap:DWLNSadvancepc}{DW\-\_LNS\-\_advance\-\_pc}&LEB128(0x239)&0x2, 0xb9, 0x04 \\
1055 SPECIAL(2, 0)&0xb  & \\
1056 SPECIAL(2, 3)&0x38 & \\
1057 SPECIAL(1, 8)&0x82 & \\
1058 SPECIAL(1, 7)&0x73 & \\
1059 \livelink{chap:DWLNSadvancepc}{DW\-\_LNS\-\_advance\-\_pc}&LEB128(2)&0x2, 0x2 \\
1060 \livelink{chap:DWLNEendsequence}{DW\-\_LNE\-\_end\-\_sequence} &&0x0, 0x1, 0x1 \\
1061 \end{longtable}
1062 \end{centering}
1063
1064
1065 Table \refersec{tab:linenumberprogramexamplealternateencoding}
1066 shows an alternate 
1067 encoding of the same program using 
1068 standard opcodes to advance
1069 the program counter; 
1070 this encoding occupies 22 bytes.
1071
1072 \begin{centering}
1073 \setlength{\extrarowheight}{0.1cm}
1074 \begin{longtable}{l|l|l}
1075   \caption{Line number program example: alternate encoding} 
1076   \label{tab:linenumberprogramexamplealternateencoding} \\
1077   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
1078 \endfirsthead
1079   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
1080 \endhead
1081   \hline \emph{Continued on next page}
1082 \endfoot
1083   \hline
1084 \endlastfoot
1085 \livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc}&0x239&0x9, 0x39, 0x2        \\
1086 SPECIAL(2, 0)&& 0xb        \\
1087 \livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc}&0x3&0x9, 0x3, 0x0        \\
1088 SPECIAL(2, 0)&&0xb        \\
1089 \livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc}&0x8&0x9, 0x8, 0x0        \\
1090 SPECIAL(1, 0)&& 0xa        \\
1091 \livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc}&0x7&0x9, 0x7, 0x0        \\
1092 SPECIAL(1, 0) && 0xa        \\
1093 \livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc}&0x2&0x9, 0x2, 0x0        \\
1094 \livelink{chap:DWLNEendsequence}{DW\-\_LNE\-\_end\-\_sequence}&&0x0, 0x1, 0x1        \\
1095 \end{longtable}
1096 \end{centering}
1097
1098
1099 \section{Call Frame Information Example}
1100 \label{app:callframeinformationexample}
1101
1102 The following example uses a hypothetical RISC machine in
1103 the style of the Motorola 88000.
1104 \begin{itemize}
1105 \item Memory is byte addressed.
1106
1107 \item Instructions are all 4 bytes each and word aligned.
1108
1109 \item Instruction operands are typically of the form:
1110 \begin{alltt}
1111     <destination.reg>, <source.reg>, <constant>
1112 \end{alltt}
1113
1114 \item The address for the load and store instructions is computed
1115 by adding the contents of the
1116 source register with the constant.
1117
1118 \item There are 8 4\dash byte registers:
1119 \begin{alltt}
1120     R0 always 0
1121     R1 holds return address on call
1122     R2-R3 temp registers (not preserved on call)
1123     R4-R6 preserved on call
1124     R7 stack pointer.
1125 \end{alltt}
1126
1127 \item  The stack grows in the negative direction.
1128
1129 \item The architectural ABI committee specifies that the
1130 stack pointer (R7) is the same as the CFA
1131
1132 \end{itemize}
1133
1134 Figure \referfol{fig:callframeinformationexamplemachinecodefragments}
1135 shows two code fragments from a subroutine called
1136 foo that uses a frame pointer (in addition to the stack
1137 pointer). The first column values are byte addresses. 
1138 % The \space is so we get a space after >
1139 \textless fs\textgreater\ denotes the stack frame size in bytes, namely 12.
1140
1141
1142 \begin{figure}[here]
1143 \begin{lstlisting}
1144        ;; start prologue
1145 foo    sub R7, R7, <fs>        ; Allocate frame
1146 foo+4  store R1, R7, (<fs>-4)  ; Save the return address
1147 foo+8  store R6, R7, (<fs>-8)  ; Save R6
1148 foo+12 add R6, R7, 0           ; R6 is now the Frame ptr
1149 foo+16 store R4, R6, (<fs>-12) ; Save a preserved reg
1150        ;; This subroutine does not change R5
1151        ...
1152        ;; Start epilogue (R7 is returned to entry value)
1153 foo+64 load R4, R6, (<fs>-12)  ; Restore R4
1154 foo+68 load R6, R7, (<fs>-8)   ; Restore R6
1155 foo+72 load R1, R7, (<fs>-4)   ; Restore return address
1156 foo+76 add R7, R7, <fs>        ; Deallocate frame
1157 foo+80 jump R1 ; Return
1158 foo+84
1159 \end{lstlisting}
1160 \caption{Call frame information example: machine code fragments}
1161 \label{fig:callframeinformationexamplemachinecodefragments}
1162 \end{figure}
1163
1164
1165 An abstract table 
1166 (see Section \refersec{chap:structureofcallframeinformation}) 
1167 for the foo subroutine is shown in 
1168 Table \referfol{tab:callframeinformationexampleconceptualmatrix}.
1169 Corresponding fragments from the
1170 \addtoindex{.debug\_frame} section are shown in 
1171 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
1172
1173 The following notations apply in 
1174 Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
1175
1176 \begin{alltt}
1177 1. R8 is the return address
1178 2. s = same\_value rule
1179 3. u = undefined rule
1180 4. rN = register(N) rule
1181 5. cN = offset(N) rule
1182 6. a = architectural rule
1183 \end{alltt}
1184
1185 \begin{centering}
1186 \setlength{\extrarowheight}{0.1cm}
1187 \begin{longtable}{l|llllllllll}
1188   \caption{Call frame information example: conceptual matrix} 
1189   \label{tab:callframeinformationexampleconceptualmatrix} \\
1190   \hline \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
1191 \endfirsthead
1192   \bfseries Location &\bfseries CFA &\bfseries R0 & \bfseries R1 & \bfseries R2 &\bfseries R3 &\bfseries R4 &\bfseries R5 &\bfseries R6 &\bfseries R7 &\bfseries R8\\ \hline
1193 \endhead
1194   \hline \emph{Continued on next page}
1195 \endfoot
1196   \hline
1197 \endlastfoot
1198 foo&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
1199 foo+4&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
1200 foo+8&[R7]+fs&s&u&u&u&s&s&s&a&c-4 \\
1201 foo+12&[R7]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
1202 foo+16&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
1203 foo+20&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
1204 ...&&&&&&&&&& \\
1205 foo+64&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
1206 foo+68&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4  \\
1207 foo+72&[R7]+fs&s&u&u&u&s&s&s&a&c-4  \\
1208 foo+76&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
1209 foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
1210 \end{longtable}
1211 \end{centering}
1212
1213 \clearpage      % ?????
1214
1215 \begin{centering}
1216 \setlength{\extrarowheight}{0.1cm}
1217 \begin{longtable}{l|ll}
1218   \caption{Call frame information example: common information entry encoding} 
1219   \label{tab:callframeinformationexamplecommoninformationentryencoding} 
1220   \\
1221   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1222 \endfirsthead
1223   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1224 \endhead
1225   \hline \emph{Continued on next page}
1226 \endfoot
1227   \hline
1228 \endlastfoot
1229 cie&36&length    \\
1230 cie+4&0xffffffff&CIE\_id    \\
1231 cie+8&4&version    \\
1232 cie+9&0&augmentation     \\
1233 cie+10&4&address size    \\
1234 cie+11&0&segment size    \\
1235 cie+12&4&code\_alignment\_factor, \textless caf \textgreater    \\
1236 cie+13&-4&data\_alignment\_factor, \textless daf \textgreater    \\
1237 cie+14&8&R8 is the return addr.    \\
1238 cie+15&\livelink{chap:DWCFAdefcfa}{DW\-\_CFA\-\_def\-\_cfa} (7, 0)&CFA = [R7]+0    \\
1239 cie+18&\livelink{chap:DWCFAsamevalue}{DW\-\_CFA\-\_same\-\_value} (0)&R0 not modified (=0)    \\
1240 cie+20&\livelink{chap:DWCFAundefined}{DW\-\_CFA\-\_undefined} (1)&R1 scratch    \\
1241 cie+22&\livelink{chap:DWCFAundefined}{DW\-\_CFA\-\_undefined} (2)&R2 scratch    \\
1242 cie+24&\livelink{chap:DWCFAundefined}{DW\-\_CFA\-\_undefined} (3)&R3 scratch    \\
1243 cie+26&\livelink{chap:DWCFAsamevalue}{DW\-\_CFA\-\_same\-\_value} (4)&R4 preserve    \\
1244 cie+28&\livelink{chap:DWCFAsamevalue}{DW\-\_CFA\-\_same\-\_value} (5)&R5 preserve    \\
1245 cie+30&\livelink{chap:DWCFAsamevalue}{DW\-\_CFA\-\_same\-\_value} (6)&R6 preserve    \\
1246 cie+32&\livelink{chap:DWCFAsamevalue}{DW\-\_CFA\-\_same\-\_value} (7)&R7 preserve    \\
1247 cie+34&\livelink{chap:DWCFAregister}{DW\-\_CFA\-\_register} (8, 1)&R8 is in R1    \\
1248 cie+37&\livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop} &padding    \\
1249 cie+38&\livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop} &padding \\
1250 cie+39& \livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop}&padding  \\
1251 cie+40 &&  \\
1252 \end{longtable}
1253 \end{centering}
1254
1255
1256 The following notations apply in 
1257 Table \refersec{tab:callframeinformationexampleframedescriptionentryencoding}:
1258
1259 \begin{alltt}
1260 1. <fs>  = frame size
1261 2. <caf> = code alignment factor
1262 3. <daf> = data alignment factor
1263 \end{alltt}
1264
1265
1266 \begin{centering}
1267 \setlength{\extrarowheight}{0.1cm}
1268 \begin{longtable}{l|ll}
1269   \caption{Call frame information example: frame description entry encoding} 
1270   \label{tab:callframeinformationexampleframedescriptionentryencoding} \\
1271   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1272 \endfirsthead
1273   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
1274 \endhead
1275   \hline \emph{Continued on next page}
1276 \endfoot
1277   \hline
1278 \endlastfoot
1279 fde&40&length \\
1280 fde+4&cie&CIE\_ptr \\
1281 fde+8&foo&initial\_location \\
1282 fde+12&84&address\_range \\
1283 fde+16&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1)&instructions \\
1284 fde+17&\livelink{chap:DWCFAdefcfaoffset}{DW\-\_CFA\-\_def\-\_cfa\-\_offset}(12)& \textless fs\textgreater \\
1285 fde+19&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1)&4/\textless caf\textgreater \\
1286 fde+20&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(8,1)&-4/\textless daf\textgreater (2nd parameter) \\
1287 fde+22&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1)& \\
1288 fde+23&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(6,2)&-8/\textless daf\textgreater (2nd parameter)  \\
1289 fde+25&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1) & \\
1290 fde+26&\livelink{chap:DWCFAdefcfaregister}{DW\-\_CFA\-\_def\-\_cfa\-\_register}(6) & \\
1291 fde+28&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1) & \\
1292 fde+29&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(4,3)&-12/\textless daf\textgreater (2nd parameter) \\
1293 fde+31&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(12)&44/\textless caf\textgreater \\
1294 fde+32&\livelink{chap:DWCFArestore}{DW\-\_CFA\-\_restore}(4)& \\
1295 fde+33&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1) & \\
1296 fde+34&\livelink{chap:DWCFArestore}{DW\-\_CFA\-\_restore}(6) & \\
1297 fde+35&\livelink{chap:DWCFAdefcfaregister}{DW\-\_CFA\-\_def\-\_cfa\-\_register}(7)  & \\
1298 fde+37&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1) & \\
1299 fde+38&\livelink{chap:DWCFArestore}{DW\-\_CFA\-\_restore}(8) &\\
1300 fde+39&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1) &\\
1301 fde+40&\livelink{chap:DWCFAdefcfaoffset}{DW\-\_CFA\-\_def\-\_cfa\-\_offset}(0)  &\\
1302 fde+42&\livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop}&padding \\
1303 fde+43&\livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop}&padding \\
1304 fde+44 && \\
1305 \end{longtable}
1306 \end{centering}
1307
1308 \section{Inlining Examples}
1309 \label{app:inliningexamples}
1310 The pseudo\dash source in 
1311 Figure \referfol{fig:inliningexamplespseudosourcefragment}
1312 is used to illustrate the
1313 \addtoindexx{inlined subprogram call!examples}
1314 use of DWARF to describe inlined subroutine calls. This
1315 example involves a nested subprogram INNER that makes uplevel
1316 references to the formal parameter and local variable of the
1317 containing subprogram OUTER.
1318
1319 \begin{figure}[here]
1320 \begin{lstlisting}
1321 inline procedure OUTER (OUTER_FORMAL : integer) =
1322     begin
1323     OUTER_LOCAL : integer;
1324     procedure INNER (INNER_FORMAL : integer) =
1325         begin
1326         INNER_LOCAL : integer;
1327         print(INNER_FORMAL + OUTER_LOCAL);
1328         end;
1329     INNER(OUTER_LOCAL);
1330     ...
1331     INNER(31);
1332     end;
1333 ! Call OUTER
1334 !
1335 OUTER(7);
1336 \end{lstlisting}
1337 \caption{Inlining examples: pseudo-source fragmment} 
1338 \label{fig:inliningexamplespseudosourcefragment}
1339 \end{figure}
1340
1341
1342 There are several approaches that a compiler might take to
1343 inlining for this sort of example. This presentation considers
1344 three such approaches, all of which involve inline expansion
1345 of subprogram OUTER. (If OUTER is not inlined, the inlining
1346 reduces to a simpler single level subset of the two level
1347 approaches considered here.)
1348
1349 The approaches are:
1350 \begin{enumerate}[1. ]
1351 \item  Inline both OUTER and INNER in all cases
1352
1353 \item Inline OUTER, multiple INNERs \\
1354 Treat INNER as a non\dash inlinable part of OUTER, compile and
1355 call a distinct normal version of INNER defined within each
1356 inlining of OUTER.
1357
1358 \item Inline OUTER, one INNER \\
1359 Compile INNER as a single normal subprogram which is called
1360 from every inlining of OUTER.
1361 \end{enumerate}
1362
1363 This discussion does not consider why a compiler might choose
1364 one of these approaches; it considers only how to describe
1365 the result.
1366
1367 In the examples that follow in this section, the debugging
1368 information entries are given mnemonic labels of the following
1369 form
1370 \begin{verbatim}
1371     <io>.<ac>.<n>.<s>
1372 \end{verbatim}
1373 where
1374 \begin{description}
1375 \item[\textless io\textgreater]
1376 is either INNER or OUTER to indicate to which
1377 subprogram the debugging information entry applies, 
1378 \item[\textless ac\textgreater]
1379 is either AI or CI to indicate ``abstract instance'' or
1380 ``concrete instance'' respectively, 
1381 \item[\textless n\textgreater]
1382 is the number of the
1383 alternative being considered, and 
1384 \item[\textless s\textgreater]
1385 is a sequence number that
1386 distinguishes the individual entries. 
1387 \end{description}
1388 There is no implication
1389 that symbolic labels, nor any particular naming convention,
1390 are required in actual use.
1391
1392 For conciseness, declaration coordinates and call coordinates are omitted.
1393
1394 \subsection{Alternative \#1: inline both OUTER and INNER}
1395 \label{app:inlinebothouterandinner}
1396
1397 A suitable abstract instance for an alternative where both
1398 OUTER and INNER are always inlined is shown in 
1399 Figure \refersec{fig:inliningexample1abstractinstance}.
1400
1401 Notice in 
1402 Figure \refersec{fig:inliningexample1abstractinstance} 
1403 that the debugging information entry for
1404 INNER (labelled INNER.AI.1.1) is nested in (is a child of)
1405 that for OUTER (labelled OUTER.AI.1.1). Nonetheless, the
1406 abstract instance tree for INNER is considered to be separate
1407 and distinct from that for OUTER.
1408
1409 The call of OUTER shown in 
1410 Figure \refersec{fig:inliningexamplespseudosourcefragment}
1411 might be described as
1412 shown in 
1413 Figure \refersec{fig:inliningexample1concreteinstance}.
1414
1415
1416 \begin{figure}[p]
1417 \begin{dwflisting}
1418 \begin{alltt}
1419     ! Abstract instance for OUTER
1420     ! \addtoindexx{abstract instance!example}
1421 OUTER.AI.1.1:
1422     \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
1423         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER")
1424         \livelink{chap:DWATinline}{DW\-\_AT\-\_inline}(\livelink{chap:DWINLdeclaredinlined}{DW\-\_INL\-\_declared\-\_inlined})
1425         ! No low/high PCs
1426 OUTER.AI.1.2:
1427         \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1428             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER\_FORMAL")
1429             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to integer)
1430             ! No location
1431 OUTER.AI.1.3:
1432         \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1433             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER\_LOCAL")
1434             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to integer)
1435             ! No location
1436         !
1437         ! Abstract instance for INNER
1438         !
1439 INNER.AI.1.1:
1440         \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
1441             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("INNER")
1442             \livelink{chap:DWATinline}{DW\-\_AT\-\_inline}(\livelink{chap:DWINLdeclaredinlined}{DW\-\_INL\-\_declared\-\_inlined})
1443             ! No low/high PCs
1444 INNER.AI.1.2:
1445             \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1446                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("INNER\_FORMAL")
1447                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to integer)
1448                 ! No location
1449 INNER.AI.1.3:
1450             \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1451                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("INNER\_LOCAL")
1452                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to integer)
1453                 ! No location
1454             ...
1455             0
1456         ! No \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine} (concrete instance)
1457         ! for INNER corresponding to calls of INNER
1458         ...
1459         0
1460 \end{alltt}
1461 \end{dwflisting}
1462 \caption{Inlining example \#1: abstract instance}
1463 \label{fig:inliningexample1abstractinstance}
1464 \end{figure}
1465
1466 \begin{figure}[p]
1467 \begin{dwflisting}
1468 \begin{alltt}
1469 ! Concrete instance for call "OUTER(7)"
1470 ! \addtoindexx{concrete instance!example}
1471 OUTER.CI.1.1:
1472     \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
1473         ! No name
1474         \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to OUTER.AI.1.1)
1475         \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}(...)
1476         \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}(...)
1477 OUTER.CI.1.2:
1478         \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1479             ! No name
1480             \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to OUTER.AI.1.2)
1481             \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}(7)
1482 OUTER.CI.1.3:
1483         \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1484             ! No name
1485             \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to OUTER.AI.1.3)
1486             \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...)
1487         !
1488         ! No \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} (abstract instance) for INNER
1489         !
1490         ! Concrete instance for call INNER(OUTER\_LOCAL)
1491         !
1492 INNER.CI.1.1:
1493         \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
1494             ! No name
1495             \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to INNER.AI.1.1)
1496             \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}(...)
1497             \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}(...)
1498             \livelink{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link}(...)
1499 INNER.CI.1.2:
1500             \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1501                 ! No name
1502                 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to INNER.AI.1.2)
1503                 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...)
1504 INNER.CI.1.3:
1505              \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1506                 ! No name
1507                 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to INNER.AI.1.3)
1508                 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...)
1509             ...
1510             0
1511         ! Another concrete instance of INNER within OUTER
1512         ! for the call "INNER(31)"
1513         ...
1514         0
1515 \end{alltt}
1516 \end{dwflisting}
1517 \caption{Inlining example \#1: concrete instance}
1518 \label{fig:inliningexample1concreteinstance}
1519 \end{figure}
1520
1521 \subsection{Alternative \#2: Inline OUTER, multiple INNERs}
1522 \label{app:inlineoutermultiipleinners}
1523
1524
1525 In the second alternative we assume that subprogram INNER
1526 is not inlinable for some reason, but subprogram OUTER is
1527 inlinable. 
1528 \addtoindexx{concrete instance!example}
1529 Each concrete inlined instance of OUTER has its
1530 own normal instance of INNER. 
1531 The abstract instance for OUTER,
1532 \addtoindexx{abstract instance!example}
1533 which includes INNER, is shown in 
1534 Figure \refersec{fig:inliningexample2abstractinstance}.
1535
1536 Note that the debugging information in this Figure differs from
1537 that in 
1538 Figure \refersec{fig:inliningexample1abstractinstance}
1539 in that INNER lacks a 
1540 \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute
1541 and therefore is not a distinct abstract instance. INNER
1542 is merely an out\dash of\dash line routine that is part of OUTER\textquoteright s
1543 abstract instance. This is reflected in the Figure by
1544 \addtoindexx{abstract instance!example}
1545 the fact that the labels for INNER use the substring OUTER
1546 instead of INNER.
1547
1548 A resulting 
1549 \addtoindexx{concrete instance!example}
1550 concrete inlined instance of OUTER is shown in
1551 Figure \refersec{fig:inliningexample2concreteinstance}.
1552
1553 Notice in 
1554 Figure \refersec{fig:inliningexample2concreteinstance}.
1555 that OUTER is expanded as a concrete
1556 \addtoindexx{concrete instance!example}
1557 inlined instance, and that INNER is nested within it as a
1558 concrete out\dash of\dash line subprogram. Because INNER is cloned
1559 for each inline expansion of OUTER, only the invariant
1560 attributes of INNER 
1561 (for example, \livelink{chap:DWATname}{DW\-\_AT\-\_name}) are specified
1562 in the abstract instance of OUTER, and the low\dash level,
1563 \addtoindexx{abstract instance!example}
1564 instance\dash specific attributes of INNER (for example,
1565 \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}) are specified in 
1566 each concrete instance of OUTER.
1567 \addtoindexx{concrete instance!example}
1568 The several calls of INNER within OUTER are compiled as normal
1569 calls to the instance of INNER that is specific to the same
1570 instance of OUTER that contains the calls.
1571
1572 \begin{figure}[t]
1573 \begin{dwflisting}
1574 \begin{alltt}
1575     ! Abstract instance for OUTER
1576     ! \addtoindex{abstract instance}
1577 OUTER.AI.2.1:
1578     \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
1579         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER")
1580         \livelink{chap:DWATinline}{DW\-\_AT\-\_inline}(\livelink{chap:DWINLdeclaredinlined}{DW\-\_INL\-\_declared\-\_inlined})
1581         ! No low/high PCs
1582 OUTER.AI.2.2:
1583         \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1584             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER\_FORMAL")
1585             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to integer)
1586             ! No location
1587 OUTER.AI.2.3:
1588         \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1589             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER\_LOCAL")
1590             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to integer)
1591             ! No location
1592         !
1593         ! Nested out-of-line INNER subprogram
1594         !
1595 OUTER.AI.2.4:
1596         \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
1597             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("INNER")
1598             ! No \livelink{chap:DWATinline}{DW\-\_AT\-\_inline}
1599             ! No low/high PCs, frame\_base, etc.
1600 OUTER.AI.2.5:
1601             \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1602                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("INNER\_FORMAL")
1603                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to integer)
1604                 ! No location
1605 OUTER.AI.2.6:
1606             \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1607                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("INNER\_LOCAL")
1608                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to integer)
1609                 ! No location
1610             ...
1611             0
1612         ...
1613         0
1614 \end{alltt}
1615 \end{dwflisting}
1616 \caption{Inlining example \#2: abstract instance}
1617 \label{fig:inliningexample2abstractinstance}
1618 \end{figure}
1619
1620 \begin{figure}[t]
1621 \begin{dwflisting}
1622 \begin{alltt}
1623
1624     ! Concrete instance for call "OUTER(7)"
1625     !
1626 OUTER.CI.2.1:
1627     \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
1628         ! No name
1629         \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to OUTER.AI.2.1)
1630         \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}(...)
1631         \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}(...)
1632 OUTER.CI.2.2:
1633         \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1634             ! No name
1635             \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to OUTER.AI.2.2)
1636             \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...)
1637 OUTER.CI.2.3:
1638         \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1639             ! No name
1640             \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to OUTER.AI.2.3)
1641             \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...)
1642         !
1643         ! Nested out-of-line INNER subprogram
1644         !
1645 OUTER.CI.2.4:
1646         \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
1647             ! No name
1648             \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to OUTER.AI.2.4)
1649             \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}(...)
1650             \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}(...)
1651             \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base}(...)
1652             \livelink{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link}(...)
1653 OUTER.CI.2.5:
1654             \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1655                 ! No name
1656                 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to OUTER.AI.2.5)
1657                 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...)
1658 OUTER.CI.2.6:
1659             \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1660                 ! No name
1661                 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to OUTER.AT.2.6)
1662                 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...)
1663             ...
1664             0
1665         ...
1666         0
1667 \end{alltt}
1668 \end{dwflisting}
1669 \caption{Inlining example \#2: concrete instance}
1670 \label{fig:inliningexample2concreteinstance}
1671 \end{figure}
1672
1673 \subsection{Alternative \#3: inline OUTER, one normal INNER}
1674 \label{app:inlineouteronenormalinner}
1675
1676 In the third approach, one normal subprogram for INNER is
1677 compiled which is called from all concrete inlined instances of
1678 \addtoindexx{concrete instance!example}
1679 \addtoindexx{abstract instance!example}
1680 OUTER. The abstract instance for OUTER is shown in 
1681 Figure \refersec{fig:inliningexample3abstractinstance}.
1682
1683 The most distinctive aspect of that Figure is that subprogram
1684 INNER exists only within the abstract instance of OUTER,
1685 and not in OUTER\textquoteright s concrete instance. In the abstract
1686 \addtoindexx{concrete instance!example}
1687 \addtoindexx{abstract instance!example}
1688 instance of OUTER, the description of INNER has the full
1689 complement of attributes that would be expected for a
1690 normal subprogram. 
1691 While attributes such as 
1692 \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc},
1693 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}, 
1694 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location},
1695 and so on, typically are omitted
1696 \addtoindexx{high PC attribute}
1697 from 
1698 \addtoindexx{low PC attribute}
1699 an 
1700 \addtoindexx{location attribute}
1701 abstract instance because they are not invariant across
1702 instances of the containing abstract instance, in this case
1703 those same attributes are included precisely because they are
1704 invariant -- there is only one subprogram INNER to be described
1705 and every description is the same.
1706
1707 A concrete inlined instance of OUTER is illustrated in
1708 Figure \refersec{fig:inliningexample3concreteinstance}.
1709
1710 Notice in 
1711 Figure \refersec{fig:inliningexample3abstractinstance}
1712 that there is no DWARF representation for
1713 INNER at all; the representation of INNER does not vary across
1714 instances of OUTER and the abstract instance of OUTER includes
1715 the complete description of INNER, so that the description of
1716 INNER may be (and for reasons of space efficiency, should be)
1717 omitted from each 
1718 \addtoindexx{concrete instance!example}
1719 concrete instance of OUTER.
1720
1721 There is one aspect of this approach that is problematical from
1722 the DWARF perspective. The single compiled instance of INNER
1723 is assumed to access up\dash level variables of OUTER; however,
1724 those variables may well occur at varying positions within
1725 the frames that contain the 
1726 \addtoindexx{concrete instance!example}
1727 concrete inlined instances. A
1728 compiler might implement this in several ways, including the
1729 use of additional compiler generated parameters that provide
1730 reference parameters for the up\dash level variables, or a compiler
1731 generated static link like parameter that points to the group
1732 of up\dash level entities, among other possibilities. In either of
1733 these cases, the DWARF description for the location attribute
1734 of each uplevel variable needs to be different if accessed
1735 from within INNER compared to when accessed from within the
1736 instances of OUTER. An implementation is likely to require
1737 vendor\dash specific DWARF attributes and/or debugging information
1738 entries to describe such cases.
1739
1740 Note that in C++, a member function of a class defined within
1741 a function definition does not require any vendor\dash specific
1742 extensions because the C++ language disallows access to
1743 entities that would give rise to this problem. (Neither extern
1744 variables nor static members require any form of static link
1745 for accessing purposes.)
1746
1747 \begin{figure}[t]
1748 \begin{dwflisting}
1749 \begin{alltt}
1750     ! Abstract instance for OUTER
1751     ! \addtoindexx{abstract instance!example}
1752 OUTER.AI.3.1:
1753     \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
1754         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER")
1755         \livelink{chap:DWATinline}{DW\-\_AT\-\_inline}(\livelink{chap:DWINLdeclaredinlined}{DW\-\_INL\-\_declared\-\_inlined})
1756         ! No low/high PCs
1757 OUTER.AI.3.2:
1758         \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1759             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER\_FORMAL")
1760             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to integer)
1761             ! No location
1762 OUTER.AI.3.3:
1763         \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1764             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER\_LOCAL")
1765             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to integer)
1766             ! No location
1767         !
1768         ! Normal INNER
1769         !
1770 OUTER.AI.3.4:
1771         \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
1772             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("INNER")
1773             \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}(...)
1774             \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}(...)
1775             \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base}(...)
1776             \livelink{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link}(...)
1777 OUTER.AI.3.5:
1778             \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1779                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("INNER\_FORMAL")
1780                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to integer)
1781                 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...)
1782 OUTER.AI.3.6:
1783             \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1784                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("INNER\_LOCAL")
1785                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to integer)
1786                 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...)
1787             ...
1788             0
1789         ...
1790         0
1791 \end{alltt}
1792 \end{dwflisting}
1793 \caption{Inlining example \#3: abstract instance}
1794 \label{fig:inliningexample3abstractinstance}
1795 \end{figure}
1796
1797 \begin{figure}[t]
1798 \begin{dwflisting}
1799 \begin{alltt}
1800     ! Concrete instance for call "OUTER(7)"
1801     ! \addtoindexx{concrete instance!example}
1802 OUTER.CI.3.1:
1803     \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
1804         ! No name
1805         \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to OUTER.AI.3.1)
1806         \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}(...)
1807         \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}(...)
1808         \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base}(...)
1809 OUTER.CI.3.2:
1810         \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1811             ! No name
1812             \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to OUTER.AI.3.2)
1813             ! No type
1814             \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...)
1815 OUTER.CI.3.3:
1816         \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1817             ! No name
1818             \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to OUTER.AI.3.3)
1819             ! No type
1820             \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(...)
1821         ! No \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} for "INNER"
1822         ...
1823         0
1824 \end{alltt}
1825 \end{dwflisting}
1826 \caption{Inlining example \#3: concrete instance}
1827 \label{fig:inliningexample3concreteinstance}
1828 \end{figure}
1829
1830 \clearpage
1831 \section{Constant Expression Example}
1832 \label{app:constantexpressionexample}
1833 C++ generalizes the notion of constant expressions to include
1834 constant expression user-defined literals and functions.
1835 The constant declarations in Figure \refersec{fig:constantexpressionscsource}
1836 can be represented as illustrated in 
1837 Figure \refersec{fig:constantexpressionsdwarfdescription}.
1838
1839
1840 \begin{figure}[here]
1841 \begin{lstlisting}[numbers=none]
1842 constexpr double mass = 9.8;
1843 constexpr int square (int x) { return x * x; }
1844 float arr[square(9)]; // square() called and inlined
1845 \end{lstlisting}
1846 \caption{Constant expressions: C++ source} \label{fig:constantexpressionscsource}
1847 \end{figure}
1848
1849
1850 \begin{figure}[!h]
1851 \begin{dwflisting}
1852 \begin{alltt}
1853         ! For variable mass
1854         !
1855 1\$:     \livelink{chap:DWTAGconsttype}{DW\-\_TAG\-\_const\-\_type}
1856             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "double")
1857 2\$:     \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1858             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("mass")
1859             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
1860             \livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr}(true)
1861             \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}(9.8)
1862         ! Abstract instance for square
1863         !
1864 10\$:    \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
1865             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("square")
1866             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "int")
1867             \livelink{chap:DWATinline}{DW\-\_AT\-\_inline}(\livelink{chap:DWINLinlined}{DW\-\_INL\-\_inlined})
1868 11\$:    \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1869             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("x")
1870             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "int")
1871         ! Concrete instance for square(9)
1872         ! \addtoindexx{concrete instance!example}
1873 20\$:    \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
1874             \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to 10\$)
1875             \livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr}(present)
1876             \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}(81)
1877         \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
1878             \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to 11\$)
1879             \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}(9)
1880         ! Anonymous array type for arr
1881         !
1882 30\$:    \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type}
1883         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "float")
1884             \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}(324) ! 81*4
1885         \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
1886             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "int")
1887             \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}(reference to 20\$)
1888         ! Variable arr
1889         !
1890 40\$:    \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1891             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("arr")
1892             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 30\$)
1893 \end{alltt}
1894 \end{dwflisting}
1895 \caption{Constant expressions: DWARF description}
1896 \label{fig:constantexpressionsdwarfdescription}
1897 \end{figure}
1898
1899 \section{Unicode Character Example}
1900 \label{app:unicodecharacterexample}
1901 \addtoindexx{Unicode|see {\textit{also} UTF-8}}
1902 The \addtoindex{Unicode} character encodings in
1903 Figure \refersec{fig:unicodecharacterexamplesource}
1904 can be described in DWARF as illustrated in 
1905 Figure \refersec{fig:unicodecharacterexampledwarfdescription}.
1906
1907 \begin{figure}[!h]
1908 \begin{lstlisting}[numbers=none]
1909 // C++ source
1910 //
1911 char16_t chr_a = u'h';
1912 char32_t chr_b = U'h';
1913 \end{lstlisting}
1914 \caption{Unicode character example: source}
1915 \label{fig:unicodecharacterexamplesource}
1916 \end{figure}
1917
1918 \begin{figure}[h]
1919 \begin{dwflisting}
1920 \begin{alltt}
1921
1922 ! DWARF description
1923 !
1924 1\$: \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
1925         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("char16\_t")
1926         \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding}(\livelink{chap:DWATEUTF}{DW\-\_ATE\-\_UTF})
1927         \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}(2)
1928 2\$: \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
1929         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("char32\_t")
1930         \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding}(\livelink{chap:DWATEUTF}{DW\-\_ATE\-\_UTF})
1931         \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}(4)
1932 3\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1933         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("chr\_a")
1934         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
1935 4\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1936         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("chr\_b")
1937         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 2\$)
1938 \end{alltt}
1939 \end{dwflisting}
1940 \caption{Unicode character example: DWARF description}
1941 \label{fig:unicodecharacterexampledwarfdescription}
1942 \end{figure}
1943
1944
1945 \section{Type-Safe Enumeration Example}
1946 \label{app:typesafeenumerationexample}
1947
1948 The \addtoindex{C++} type\dash safe enumerations in
1949 \addtoindexx{type-safe enumeration}
1950 Figure \refersec{fig:ctypesafeenumerationexamplesource}
1951 can be described in DWARF as illustrated in 
1952 Figure \refersec{fig:ctypesafeenumerationexampledwarf}.
1953
1954 \begin{figure}[H]
1955 \begin{lstlisting}[numbers=none]
1956 // C++ source
1957 //
1958 enum class E { E1, E2=100 };
1959 E e1;
1960 \end{lstlisting}
1961 \caption{Type-safe enumeration example: source}
1962 \label{fig:ctypesafeenumerationexamplesource}
1963 \end{figure}
1964
1965 \begin{figure}[H]
1966 \begin{dwflisting}
1967 \begin{alltt}
1968 ! DWARF description
1969 !
1970 11\$: \livelink{chap:DWTAGenumerationtype}{DW\-\_TAG\-\_enumeration\-\_type}
1971         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("E")
1972         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "int")
1973         \livelink{chap:DWATenumclass}{DW\-\_AT\-\_enum\-\_class}(present)
1974 12\$:   \livelink{chap:DWTAGenumerator}{DW\-\_TAG\-\_enumerator}
1975             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("E1")
1976             \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}(0)
1977 13\$:
1978          \livelink{chap:DWTAGenumerator}{DW\-\_TAG\-\_enumerator}
1979             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("E2")
1980             \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}(100)
1981 14\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1982         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("e1")
1983         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 11\$)
1984 \end{alltt}
1985 \end{dwflisting}
1986 \caption{Type-safe enumeration example: DWARF description}
1987 \label{fig:ctypesafeenumerationexampledwarf}
1988 \end{figure}
1989
1990
1991 \clearpage
1992 \section{Template Examples}
1993 \label{app:templateexample}
1994
1995 The C++ template example in
1996 Figure \refersec{fig:ctemplateexample1source}
1997 can be described in DWARF as illustrated in 
1998 Figure \refersec{fig:ctemplateexample1dwarf}.
1999
2000 \begin{figure}[h]
2001 \begin{lstlisting}
2002 // C++ source
2003 //
2004 template<class T>
2005 struct wrapper {
2006     T comp;
2007 };
2008 wrapper<int> obj;
2009 \end{lstlisting}
2010 \caption{C++ template example \#1: source}
2011 \label{fig:ctemplateexample1source}
2012 \end{figure}
2013
2014 \begin{figure}[h]
2015 \begin{dwflisting}
2016 \begin{alltt}
2017 ! DWARF description
2018 !
2019 11\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
2020         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("wrapper")
2021 12\$: \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}
2022         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("T")
2023         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "int")
2024 13\$ \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
2025         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("comp")
2026         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 12\$)
2027 14\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
2028         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("obj")
2029         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 11\$)
2030 \end{alltt}
2031 \end{dwflisting}
2032 \caption{C++ template example \#1: DWARF description}
2033 \label{fig:ctemplateexample1dwarf}
2034 \end{figure}
2035
2036 The actual type of the component comp is int, but in the DWARF
2037 the type references the
2038 \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}
2039 for T, which in turn references int. This implies that in the
2040 original template comp was of type T and that was replaced
2041 with int in the instance. There exist situations where it is
2042 not possible for the DWARF to imply anything about the nature
2043 of the original template. 
2044
2045 \needlines{10}
2046 Consider the C++ template source in
2047 Figure \refersec{fig:ctemplateexample2source}
2048 and the DWARF that can describe it in
2049 Figure \refersec{fig:ctemplateexample2dwarf}.
2050
2051 \begin{figure}[!h]
2052 \begin{lstlisting}
2053 // C++ source
2054 //
2055     template<class T>
2056     struct wrapper {
2057         T comp;
2058     };
2059     template<class U>
2060     void consume(wrapper<U> formal)
2061     {
2062         ...
2063     }
2064     wrapper<int> obj;
2065     consume(obj);
2066 \end{lstlisting}
2067 \caption{C++ template example \#2: source}
2068 \label{fig:ctemplateexample2source}
2069 \end{figure}
2070
2071 \begin{figure}[h]
2072 \begin{dwflisting}
2073 \begin{alltt}
2074 ! DWARF description
2075 !
2076 11\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
2077         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("wrapper")
2078 12\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}
2079             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("T")
2080             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "int")
2081 13\$    \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
2082             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("comp")
2083             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 12\$)
2084 14\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
2085         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("obj")
2086         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 11\$)
2087 21\$: \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
2088         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("consume")
2089 22\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}
2090             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("U")
2091             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "int")
2092 23\$:   \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
2093             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("formal")
2094             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 11\$)
2095 \end{alltt}
2096 \end{dwflisting}
2097 \caption{C++ template example \#2: DWARF description}
2098 \label{fig:ctemplateexample2dwarf}
2099 \end{figure}
2100
2101 In the \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} 
2102 entry for the instance of consume, U is described as int. 
2103 The type of formal is \texttt{wrapper\textless U\textgreater} in
2104 the source. DWARF only represents instantiations of templates;
2105 there is no entry which represents \texttt{wrapper\textless U\textgreater} 
2106 which is neither
2107 a template parameter nor a template instantiation. The type
2108 of formal is described as \texttt{wrapper\textless int\textgreater},
2109 the instantiation of \texttt{wrapper\textless U\textgreater},
2110 in the \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute at 
2111 23\$. 
2112 There is no
2113 description of the relationship between template type parameter
2114 T at 12\$ and U at 22\$ which was used to instantiate
2115 \texttt{wrapper\textless U\textgreater}.
2116
2117 A consequence of this is that the DWARF information would
2118 not distinguish between the existing example and one where
2119 the formal of consume were declared in the source to be
2120 \texttt{wrapper\textless int\textgreater}.
2121
2122
2123 \section{Template Alias Examples}
2124 \label{app:templatealiasexample}
2125
2126 The \addtoindex{C++} template alias shown in
2127 Figure \refersec{fig:ctemplatealiasexample1source}
2128 can be described in DWARF as illustrated 
2129 \addtoindexx{template alias example} in 
2130 Figure \refersec{fig:ctemplatealiasexample1dwarf}.
2131
2132 \begin{figure}[h]
2133 \begin{lstlisting}
2134 // C++ source, template alias example 1
2135 //
2136 template<typename T, typename U>
2137 struct Alpha {
2138     T tango;
2139     U uniform;
2140 };
2141 template<typename V> using Beta = Alpha<V,V>;
2142 Beta<long> b;
2143 \end{lstlisting}
2144 \caption{C++ template alias example \#1: source}
2145 \label{fig:ctemplatealiasexample1source}
2146 \end{figure}
2147
2148 \begin{figure}[h]
2149 \addtoindexx{template alias example 1}
2150 \begin{dwflisting}
2151 \begin{alltt}
2152 ! DWARF representation for variable 'b'
2153 !
2154 20\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
2155         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("Alpha")
2156 21\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}
2157             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("T")
2158             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "long")
2159 22\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}
2160             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("U")
2161             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "long")
2162 23\$:   \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
2163             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("tango")
2164             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 21\$)
2165 24\$:   \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
2166             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("uniform")
2167             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 22\$)
2168 25\$: \livelink{chap:DWTAGtemplatealias}{DW\-\_TAG\-\_template\-\_alias}
2169         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("Beta")
2170         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 20\$)
2171 26\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}
2172             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("V")
2173             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "long")
2174 27\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
2175         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("b")
2176         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 25\$)
2177 \end{alltt}
2178 \end{dwflisting}
2179 \caption{C++ template alias example \#1: DWARF description}
2180 \label{fig:ctemplatealiasexample1dwarf}
2181 \end{figure}
2182
2183 Similarly, the \addtoindex{C++} template alias shown in
2184 Figure \refersec{fig:ctemplatealiasexample2source}
2185 can be described in DWARF as illustrated 
2186 \addtoindexx{template alias example} in 
2187 Figure \refersec{fig:ctemplatealiasexample2dwarf}.
2188
2189 \begin{figure}[h]
2190 \begin{lstlisting}
2191 // C++ source, template alias example 2
2192 //
2193 template<class TX> struct X { };
2194 template<class TY> struct Y { };
2195 template<class T> using Z = Y<T>;
2196 X<Y<int>> y;
2197 X<Z<int>> z;
2198 \end{lstlisting}
2199 \caption{C++ template alias example \#2: source}
2200 \label{fig:ctemplatealiasexample2source}
2201 \end{figure}
2202
2203 \begin{figure}[h]
2204 \addtoindexx{template alias example 2}
2205 \begin{dwflisting}
2206 \begin{alltt}
2207 ! DWARF representation for X<Y<int>>
2208 !
2209 30\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
2210         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("Y")
2211 31\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}
2212             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("TY")
2213             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "int")
2214 32\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
2215         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("X")
2216 33\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}
2217             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("TX")
2218             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 30\$)
2219
2220 ! DWARF representation for X<Z<int>>
2221 !
2222 40\$: \livelink{chap:DWTAGtemplatealias}{DW\-\_TAG\-\_template\-\_alias}
2223 using Z = Y<int>;
2224         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("Z")
2225         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 30\$)
2226 41\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}
2227             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("T")
2228             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "int")
2229 42\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
2230         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("X")
2231 43\$:   \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}
2232             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("TX")
2233             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 40\$)
2234 ! Note that 32\$ and 42\$ are actually the same type
2235 !
2236 50\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
2237         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("y")
2238         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to \$32)
2239 51\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
2240         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("z")
2241         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to \$42)
2242 \end{alltt}
2243 \end{dwflisting}
2244 \caption{C++ template alias example \#2: DWARF description}
2245 \label{fig:ctemplatealiasexample2dwarf}
2246 \end{figure}