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