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