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