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