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