Corrected some livetarg uses and added some livelink
[dwarf-doc.git] / dwarf5 / latexdoc / typeentries.tex
1 \chapter{Type Entries}
2 \label{chap:typeentries}
3 This section presents the debugging information entries
4 that describe program types: base types, modified types and
5 user\dash defined types.
6
7 If the scope of the declaration of a named type begins after
8 the low pc value for the scope most closely enclosing the
9 declaration, the declaration may have a DW\_AT\_start\_scope
10 attribute as described for objects in 
11 Section \refersec{chap:dataobjectentries}.
12
13 \section{Base Type Entries}
14 \label{chap:basetypeentries}
15
16 \textit{A base type is a data type that is not defined in terms of
17 other data types. Each programming language has a set of base
18 types that are considered to be built into that language.}
19
20 A base type is represented by a debugging information entry
21 with the tag 
22 \livetarg{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}.
23
24 A base type entry has a DW\_AT\_name attribute whose value is
25 a null\dash terminated string containing the name of the base type
26 as recognized by the programming language of the compilation
27 unit containing the base type entry.
28
29 A base type entry has a DW\_AT\_encoding attribute describing
30 how the base type is encoded and is to be interpreted. The
31 value of this attribute is an integer constant. The set of
32 values and their meanings for the DW\_AT\_encoding attribute
33 is given in 
34 Figure \refersec{fig:encodingattributevalues}
35 and following text.  
36
37 A base type entry
38 may have a DW\_AT\_endianity attribute as described in 
39 Section \refersec{chap:dataobjectentries}. 
40 If omitted, the encoding assumes the representation that
41 is the default for the target architecture.
42
43 A base type entry has either a DW\_AT\_byte\_size attribute
44 or a DW\_AT\_bit\_size attribute whose integer constant value
45 (see Section \refersec{chap:byteandbitsizes}) 
46 is the amount of storage needed to hold
47 a value of the type.
48
49 \textit{For example, the C type int on a machine that uses 32\dash bit
50 integers is represented by a base type entry with a name
51 attribute whose value is “int”, an encoding attribute
52 whose value is DW\_ATE\_signed and a byte size attribute whose
53 value is 4.}
54
55 If the value of an object of the given type does not fully
56 occupy the storage described by a byte size attribute,
57 the base type entry may also have a DW\_AT\_bit\_size and a
58 DW\_AT\_data\_bit\_offset attribute, both of whose values are
59 integer constant values (
60 see Section \refersec{chap:staticanddynamicvaluesofattributes}). 
61 The bit size
62 attribute describes the actual size in bits used to represent
63 values of the given type. The data bit offset attribute is the
64 offset in bits from the beginning of the containing storage to
65 the beginning of the value. Bits that are part of the offset
66 are padding. The data bit offset uses the bit numbering and
67 direction conventions that are appropriate to the current
68 language on the
69 target system to locate the beginning of the storage and
70 value. If this attribute is omitted a default data bit offset
71 of zero is assumed.
72
73 \textit{Attribute DW\_AT\_data\_bit\_offset is new in DWARF Version 4 and
74 is also used for bit field members 
75 (see Section \refersec{chap:datamemberentries}). 
76 It
77 replaces the attribute DW\_AT\_bit\_offset when used for base
78 types as defined in DWARF V3 and earlier. The earlier attribute
79 is defined in a manner suitable for bit field members on
80 big\dash endian architectures but which is wasteful for use on
81 little\dash endian architectures.}
82
83 \textit{The attribute DW\_AT\_bit\_offset is deprecated in DWARF Version
84 4 for use in base types, but implementations may continue to
85 support its use for compatibility.}
86
87 \textit{The DWARF Version 3 definition of these attributes is as follows.}
88
89 \begin{myindentpara}{1cm}
90 \textit{A base type entry has a DW\_AT\_byte\_size attribute, whose value
91 (see Section 2.19) is the size in bytes of the storage unit
92 used to represent an object of the given type.}
93
94 \textit{If the value of an object of the given type does not fully
95 occupy the storage unit described by the byte size attribute,
96 the base type entry may have a DW\_AT\_bit\_size attribute and a
97 DW\_AT\_bit\_offset attribute, both of whose values (see Section
98 2.19) are integers. The bit size attribute describes the actual
99 size in bits used to represent a value of the given type.
100 The bit offset attribute describes the offset in bits of the
101 high order bit of a value of the given type from the high
102 order bit of the storage unit used to contain that value.}
103 \end{myindentpara}
104
105 \textit{In comparing DWARF Versions 3 and 4, note that DWARF V4
106 defines the following combinations of attributes:}
107
108 \begin{itemize}
109 \item \textit{DW\_AT\_byte\_size}
110 \item \textit{DW\_AT\_bit\_size}
111 \item \textit{DW\_AT\_byte\_size, DW\_AT\_bit\_size 
112 and optionally DW\_AT\_data\_bit\_offset}
113 \end{itemize}
114 DWARF V3 defines the following combinations:
115 % FIXME: the figure below interferes with the following
116 % bullet list, which looks horrible as a result.
117 \begin{itemize}
118 \item \textit{DW\_AT\_byte\_size}
119 \item \textit{DW\_AT\_byte\_size, DW\_AT\_bit\_size and DW\_AT\_bit\_offset}
120 \end{itemize}
121
122 \begin{figure}[!here]
123 \centering
124 \begin{tabular}{lp{9cm}}
125 Name&Meaning\\ \hline
126 DW\_ATE\_address &  linear machine address (for
127   segmented addresses see
128   Section \refersec{chap:segmentedaddresses}) \\
129 DW\_ATE\_boolean& true or false \\
130
131 DW\_ATE\_complex\_float& complex binary floating\dash point number \\
132 DW\_ATE\_float & binary floating\dash point number \\
133 DW\_ATE\_imaginary\_float& imaginary binary floating\dash point number \\
134 DW\_ATE\_signed& signed binary integer \\
135 DW\_ATE\_signed\_char& signed character \\
136 DW\_ATE\_unsigned & unsigned binary integer \\
137 DW\_ATE\_unsigned\_char & unsigned character \\
138 DW\_ATE\_packed\_decimal  & packed decimal \\
139 DW\_ATE\_numeric\_string& numeric string \\
140 DW\_ATE\_edited & edited string \\
141 DW\_ATE\_signed\_fixed & signed fixed\dash point scaled integer \\
142 DW\_ATE\_unsigned\_fixed& unsigned fixed\dash point scaled integer \\
143 DW\_ATE\_decimal\_float & decimal floating\dash point number \\ 
144 DW\_ATE\_UTF & Unicode character \\
145 \end{tabular}
146 \caption{Encoding attribute values}
147 \label{fig:encodingattributevalues}
148 \end{figure}
149
150 \textit{The DW\_ATE\_decimal\_float encoding is intended for
151 floating\dash point representations that have a power\dash of\dash ten
152 exponent, such as that specified in IEEE 754R.}
153
154 \textit{The DW\_ATE\_UTF encoding is intended for Unicode string
155 encodings (see the Universal Character Set standard,
156 ISO/IEC 10646\dash 1:1993). For example, the C++ type char16\_t is
157 represented by a base type entry with a name attribute whose
158 value is “char16\_t”, an encoding attribute whose value
159 is DW\_ATE\_UTF and a byte size attribute whose value is 2.}
160
161 The DW\_ATE\_packed\_decimal and DW\_ATE\_numeric\_string base types
162 represent packed and unpacked decimal string numeric data
163 types, respectively, either of which may be either signed
164 or unsigned. These base types are used in combination with
165 DW\_AT\_decimal\_sign, DW\_AT\_digit\_count and DW\_AT\_decimal\_scale
166 attributes.
167
168 A DW\_AT\_decimal\_sign attribute is an integer constant that
169 conveys the representation of the sign of the decimal type
170 (see Figure \refersec{fig:decimalsignattributevalues}). 
171 Its integer constant value is interpreted to
172 mean that the type has a leading overpunch, trailing overpunch,
173 leading separate or trailing separate sign representation or,
174 alternatively, no sign at all.
175
176 The DW\_AT\_digit\_count attribute is an integer constant
177 value that represents the number of digits in an instance of
178 the type.
179
180 The DW\_AT\_decimal\_scale attribute is an integer constant value
181 that represents the exponent of the base ten scale factor to
182 be applied to an instance of the type. A scale of zero puts the
183 decimal point immediately to the right of the least significant
184 digit. Positive scale moves the decimal point to the right
185 and implies that additional zero digits on the right are not
186 stored in an instance of the type. Negative scale moves the
187 decimal point to the left; if the absolute value of the scale
188 is larger than the digit count, this implies additional zero
189 digits on the left are not stored in an instance of the type.
190
191 The DW\_ATE\_edited base type is used to represent an edited
192 numeric or alphanumeric data type. It is used in combination
193 with an DW\_AT\_picture\_string attribute whose value is a 
194 null\dash terminated string containing the target\dash dependent picture
195 string associated with the type.
196
197 If the edited base type entry describes an edited numeric
198 data type, the edited type entry has a DW\_AT\_digit\_count and a
199 DW\_AT\_decimal\_scale attribute. These attributes have the same
200 interpretation as described for the DW\_ATE\_packed\_decimal and
201 DW\_ATE\_numeric\_string base types. If the edited type entry
202 describes an edited alphanumeric data type, the edited type
203 entry does not have these attributes.
204
205
206 \textit{The presence or absence of the DW\_AT\_digit\_count and
207 DW\_AT\_decimal\_scale attributes allows a debugger to easily
208 distinguish edited numeric from edited alphanumeric, although
209 in principle the digit count and scale are derivable by
210 interpreting the picture string.}
211
212 The DW\_ATE\_signed\_fixed and DW\_ATE\_unsigned\_fixed entries
213 describe signed and unsigned fixed\dash point binary data types,
214 respectively.
215
216 The fixed binary type entries have a DW\_AT\_digit\_count
217 attribute with the same interpretation as described for the
218 DW\_ATE\_packed\_decimal and DW\_ATE\_numeric\_string base types.
219
220 For a data type with a decimal scale factor, the fixed binary
221 type entry has a DW\_AT\_decimal\_scale attribute with the same
222 interpretation as described for the DW\_ATE\_packed\_decimal
223 and DW\_ATE\_numeric\_string base types.
224
225 For a data type with a binary scale factor, the fixed
226 binary type entry has a DW\_AT\_binary\_scale attribute. The
227 DW\_AT\_binary\_scale attribute is an integer constant value
228 that represents the exponent of the base two scale factor to
229 be applied to an instance of the type.  Zero scale puts the
230 binary point immediately to the right of the least significant
231 bit. Positive scale moves the binary point to the right and
232 implies that additional zero bits on the right are not stored
233 in an instance of the type. Negative scale moves the binary
234 point to the left; if the absolute value of the scale is
235 larger than the number of bits, this implies additional zero
236 bits on the left are not stored in an instance of the type.
237
238 For a data type with a non\dash decimal and non\dash binary scale factor,
239 the fixed binary type entry has a DW\_AT\_small attribute which
240 references a DW\_TAG\_constant entry. The scale factor value
241 is interpreted in accordance with the value defined by the
242 DW\_TAG\_constant entry. The value represented is the product
243 of the integer value in memory and the associated constant
244 entry for the type.
245
246 \textit{The DW\_AT\_small attribute is defined with the Ada small
247 attribute in mind.}
248
249 \begin{figure}[here]
250 \centering
251 \begin{tabular}{lp{9cm}}
252 Name&Meaning\\ \hline
253 DW\_DS\_unsigned &  unsigned \\
254 DW\_DS\_leading\_overpunch & Sign is encoded in the most significant digit in a target\dash dependent  manner \\
255 DW\_DS\_trailing\_overpunch & Sign is encoded in the least significant digit in a target\dash dependent manner \\
256 DW\_DS\_leading\_separate & Decimal type: Sign a ``+'' or ``-'' character 
257 to the right of the least significant digit. \\
258 &Packed decimal type: Least significant nibble contains
259 a target\dash dependent value
260 indicating positive or negative. \\
261 \end{tabular}
262 \caption{Decimal sign attribute values}
263 \label{fig:decimalsignattributevalues}
264 \end{figure}
265
266 \section{Unspecified Type Entries}
267 \label{chap:unspecifiedtypeentries}
268 Some languages have constructs in which a type may be left unspecified or the absence of a type
269 may be explicitly indicated.
270
271 An unspecified (implicit, unknown, ambiguous or nonexistent)
272 type is represented by a debugging information entry with
273 the tag \livetarg{chap:DWTAGunspecifiedtype}{DW\_TAG\_unspecified\_type}. 
274 If a name has been given
275 to the type, then the corresponding unspecified type entry
276 has a DW\_AT\_name attribute whose value is a null\dash terminated
277 string containing the name as it appears in the source program.
278
279 The interpretation of this debugging information entry is
280 intentionally left flexible to allow it to be interpreted
281 appropriately in different languages. For example, in C and C++
282 the language implementation can provide an unspecified type
283 entry with the name “void” which can be referenced by the
284 type attribute of pointer types and typedef declarations for
285 'void' (see 
286 % FIXME: the following reference was wrong in DW4 so DavidA guessed
287 % the intent.
288 Sections \refersec{chap:unspecifiedtypeentries} and 
289 %The following reference was valid, so the following is probably correct.
290 Section \refersec{chap:typedefentries}, 
291 respectively). As another
292 example, in Ada such an unspecified type entry can be referred
293 to by the type attribute of an access type where the denoted
294 type is incomplete (the name is declared as a type but the
295 definition is deferred to a separate compilation unit). Type
296 Modifier Entries
297
298 A base or user\dash defined type may be modified in different ways
299 in different languages. A type modifier is represented in
300 DWARF by a debugging information entry with one of the tags
301 given in 
302 Figure \refersec{fig:typemodifiertags}.
303
304
305 If a name has been given to the modified type in the source
306 program, then the corresponding modified type entry has
307 a DW\_AT\_name attribute whose value is a null-terminated
308 string containing the modified type name as it appears in
309 the source program.
310
311 Each of the type modifier entries has a DW\_AT\_type attribute,
312 whose value is a reference to a debugging information entry
313 describing a base type, a user-defined type or another type
314 modifier.
315
316 A modified type entry describing a pointer or reference
317 type (using DW\_TAG\_pointer\_type, DW\_TAG\_reference\_type or
318 DW\_TAG\_rvalue\_reference\_type) may have a DW\_AT\_address\_class
319 attribute to describe how objects having the given pointer
320 or reference type ought to be dereferenced.
321
322 A modified type entry describing a shared qualified type
323 (using DW\_TAG\_shared\_type) may have a DW\_AT\_count attribute
324 whose value is a constant expressing the blocksize of the
325 type. If no count attribute is present, then the “infinite”
326 blocksize is assumed.
327
328 When multiple type modifiers are chained together to modify
329 a base or user-defined type, the tree ordering reflects the
330 semantics of the applicable lanuage rather than the textual
331 order in the source presentation.
332
333 \begin{figure}[here]
334 \centering
335 \begin{tabular}{lp{9cm}}
336 Name&Meaning\\ \hline
337 \livetarg{chap:DWTAGconsttype}{DW\_TAG\_const\_type} &  C or C++ const qualified type \\
338 \livetarg{chap:DWTAGpackedtype}{DW\_TAG\_packed\_type}& Pascal or Ada packed type \\
339 \livetarg{chap:DWTAGpointertype}{DW\_TAG\_pointer\_type} & Pointer to an object of the type being modified \\
340 \livetarg{chap:DWTAGreferencetype}{DW\_TAG\_reference\_type}& C++ (lvalue) reference to an object of the type 
341 being modified \\
342 \livetarg{chap:DWTAGrestricttype}{DW\_TAG\_restrict\_type}&C restrict qualified type \\
343 \livetarg{chap:DWTAGrvaluereferencetype}{DW\_TAG\_rvalue\_reference\_type} & C++ rvalue reference to an object of the type
344 being modified \\
345 \livetarg{chap:DWTAGsharedtype}{DW\_TAG\_shared\_type}&UPC shared qualified type \\
346 \livetarg{chap:DWTAGvolatiletype}{DW\_TAG\_volatile\_type}&C or C++ volatile qualified type \\
347 \end{tabular}
348 \caption{Type modifier tags}
349 \label{fig:typemodifiertags}
350 \end{figure}
351
352 % The following prevents splitting the examples up.
353 % FIXME perhaps there is a better way. We could box the verbatim, 
354 % see memman.pdf on verbatims.
355 \clearpage
356 \textit{As examples of how tye modifiers are ordered, take the following C
357 declarations:}
358
359 \begin{verbatim}
360 const unsigned char * volatile p;
361     which represents a volatile pointer to a constant
362     character. This is encoded in DWARF as:
363         DW_TAG_variable(p) -->
364             DW_TAG_volatile_type -->
365                 DW_TAG_pointer_type -->
366                     DW_TAG_const_type -->
367                         DW_TAG_base_type(unsigned char)
368
369 volatile unsigned char * const restrict p;
370     on the other hand, represents a restricted constant
371     pointer to a volatile character. This is encoded as:
372         DW_TAG_variable(p) -->
373             DW_TAG_restrict_type -->
374                 DW_TAG_const_type -->
375                     DW_TAG_pointer_type -->
376                         DW_TAG_volatile_type -->
377                             DW_TAG_base_type(unsigned char)
378
379 \end{verbatim}
380
381 \section{Typedef Entries}
382 \label{chap:typedefentries}
383 A named type that is defined in terms of another type
384 definition is represented by a debugging information entry with
385 the tag \livetarg{chap:DWTAGtypedef}{DW\_TAG\_typedef}. 
386 The typedef entry has a DW\_AT\_name
387 attribute whose value is a null-terminated string containing
388 the name of the typedef as it appears in the source program.
389
390 The typedef entry may also contain a DW\_AT\_type attribute whose
391 value is a reference to the type named by the typedef. If
392 the debugging information entry for a typedef represents
393 a declaration of the type that is not also a definition,
394 it does not contain a type attribute.
395
396 \textit{Depending on the language, a named type that is defined in
397 terms of another type may be called a type alias, a subtype,
398 a constrained type and other terms. A type name declared with
399 no defining details may be termed an incomplete, forward
400 or hidden type. While the DWARF DW\_TAG\_typedef entry was
401 originally inspired by the like named construct in C and C++,
402 it is broadly suitable for similar constructs (by whatever
403 source syntax) in other languages.}
404
405 \section{Array Type Entries}
406 \label{chap:arraytypeentries}
407
408 Many languages share the concept of an ``array,'' which is
409 a table of components of identical type.
410
411 An array type is represented by a debugging information entry
412 with the tag \livetarg{chap:DWTAGarraytype}{DW\_TAG\_array\_type}. 
413 If a name has been given to
414 the array type in the source program, then the corresponding
415 array type entry has a DW\_AT\_name attribute whose value is a
416 null-terminated string containing the array type name as it
417 appears in the source program.
418
419 The array type entry describing a multidimensional array may
420 have a DW\_AT\_ordering attribute whose integer constant value is
421 interpreted to mean either row-major or column-major ordering
422 of array elements. The set of values and their meanings
423 for the ordering attribute are listed in 
424 Figure \refersec{fig:arrayordering}. 
425 If no
426 ordering attribute is present, the default ordering for the
427 source language (which is indicated by the DW\_AT\_language
428 attribute of the enclosing compilation unit entry) is assumed.
429
430 \begin{figure}[here]
431 \autorows[0pt]{c}{1}{l}{
432 \addtoindex{DW\_ORD\_col\_major},
433 \addtoindex{DW\_ORD\_row\_major}
434 }
435 \caption{Array ordering}\label{fig:arrayordering}
436 \end{figure}
437
438 The ordering attribute may optionally appear on one-dimensional
439 arrays; it will be ignored.
440
441 An array type entry has a DW\_AT\_type attribute describing
442 the type of each element of the array.
443
444 If the amount of storage allocated to hold each element of an
445 object of the given array type is different from the amount
446 of storage that is normally allocated to hold an individual
447 object of the indicated element type, then the array type
448 entry has either a DW\_AT\_byte\_stride or a DW\_AT\_bit\_stride
449 attribute, whose value 
450 (see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
451 is the size of each
452 element of the array.
453
454 The array type entry may have either a DW\_AT\_byte\_size or a
455 DW\_AT\_bit\_size attribute 
456 (see Section \refersec{chap:byteandbitsizes}), 
457 whose value is the
458 amount of storage needed to hold an instance of the array type.
459
460 \textit{If the size of the array can be determined statically at
461 compile time, this value can usually be computed by multiplying
462 the number of array elements by the size of each element.}
463
464
465 Each array dimension is described by a debugging information
466 entry with either the tag DW\_TAG\_subrange\_type or the tag
467 DW\_TAG\_enumeration\_type. These entries are children of the
468 array type entry and are ordered to reflect the appearance of
469 the dimensions in the source program (i.e., leftmost dimension
470 first, next to leftmost second, and so on).
471
472 In languages, such as C, in which there is no concept of
473 a “multidimensional array”, an array of arrays may
474 be represented by a debugging information entry for a
475 multidimensional array.
476
477 Other attributes especially applicable to arrays are
478 DW\_AT\_allocated, DW\_AT\_associated and DW\_AT\_data\_location,
479 which are described in 
480 Section \refersec{chap:dynamictypeproperties}. 
481 For relevant examples,
482 see also 
483 Appendix \refersec{app:fortran90example}.
484
485 \section{ Structure, Union, Class and Interface Type Entries}
486 \label{chap:structureunionclassandinterfacetypeentries}
487
488 \textit{The languages C, C++, and Pascal, among others, allow the
489 programmer to define types that are collections of related
490 components. In C and C++, these collections are called
491 “structures.” In Pascal, they are called “records.”
492 The components may be of different types. The components are
493 called “members” in C and C++, and “fields” in Pascal.}
494
495 \textit{The components of these collections each exist in their
496 own space in computer memory. The components of a C or C++
497 “union” all coexist in the same memory.}
498
499 \textit{Pascal and other languages have a “discriminated union,”
500 also called a “variant record.” Here, selection of a
501 number of alternative substructures (“variants”) is based
502 on the value of a component that is not part of any of those
503 substructures (the “discriminant”).}
504
505 \textit{C++ and Java have the notion of "class”, which is in some
506 ways similar to a structure. A class may have “member
507 functions” which are subroutines that are within the scope
508 of a class or structure.}
509
510 \textit{The C++ notion of structure is more general than in C, being
511 equivalent to a class with minor differences. Accordingly,
512 in the following discussion statements about C++ classes may
513 be understood to apply to C++ structures as well.}
514
515 \subsection{Structure, Union and Class Type Entries}
516 \label{chap:structureunionandclasstypeentries}
517
518
519 Structure, union, and class types are represented by debugging
520 information entries with 
521 the tags \livetarg{chap:DWTAGstructuretype}{DW\_TAG\_structure\_type},
522 \livetarg{chap:DWTAGuniontype}{DW\_TAG\_union\_type}, 
523 and \livetarg{chap:DWTAGclasstype}{DW\_TAG\_class\_type},
524 respectively. If a name has been given to the structure,
525 union, or class in the source program, then the corresponding
526 structure type, union type, or class type entry has a
527 DW\_AT\_name attribute whose value is a null\dash terminated string
528 containing the type name as it appears in the source program.
529
530 The members of a structure, union, or class are represented
531 by debugging information entries that are owned by the
532 corresponding structure type, union type, or class type entry
533 and appear in the same order as the corresponding declarations
534 in the source program.
535
536 A structure type, union type or class type entry may have
537 either a DW\_AT\_byte\_size or a DW\_AT\_bit\_size attribute 
538 (see Section \refersec{chap:byteandbitsizes}), 
539 whose value is the amount of storage needed
540 to hold an instance of the structure, union or class type,
541 including any padding.  An incomplete structure, union or
542 class type is represented by a structure, union or class
543 entry that does not have a byte size attribute and that has
544 a DW\_AT\_declaration attribute.
545
546 If the complete declaration of a type has been placed in
547 a separate type unit 
548 (see Section \refersec{chap:separatetypeunitentries}), 
549 an incomplete
550 declaration of that type in the compilation unit may provide
551 the unique 64\dash bit signature of the type using a DW\_AT\_signature
552 attribute.
553
554 If a structure, union or class entry represents the definition
555 of a structure, class or union member corresponding to a prior
556 incomplete structure, class or union, the entry may have a
557 DW\_AT\_specification attribute whose value is a reference to
558 the debugging information entry representing that incomplete
559 declaration.
560
561 Structure, union and class entries containing the
562 DW\_AT\_specification attribute do not need to duplicate
563 information provided by the declaration entry referenced by the
564 specification attribute.  In particular, such entries do not
565 need to contain an attribute for the name of the structure,
566 class or union they represent if such information is already
567 provided in the declaration.
568
569 \textit{For C and C++, data member declarations occurring within
570 the declaration of a structure, union or class type are
571 considered to be “definitions” of those members, with
572 the exception of “static” data members, whose definitions
573 appear outside of the declaration of the enclosing structure,
574 union or class type. Function member declarations appearing
575 within a structure, union or class type declaration are
576 definitions only if the body of the function also appears
577 within the type declaration.}
578
579 If the definition for a given member of the structure, union
580 or class does not appear within the body of the declaration,
581 that member also has a debugging information entry describing
582 its definition. That latter entry has a DW\_AT\_specification
583 attribute referencing the debugging information entry
584 owned by the body of the structure, union or class entry and
585 representing a non\dash defining declaration of the data, function
586 or type member. The referenced entry will not have information
587 about the location of that member (low and high pc attributes
588 for function members, location descriptions for data members)
589 and will have a DW\_AT\_declaration attribute.
590
591 \textit{Consider a nested class whose 
592 definition occurs outside of the containing class definition, as in:}
593
594 \begin{lstlisting}
595 struct A {
596     struct B;
597 };
598 struct A::B { ... };
599 \end{lstlisting}
600
601 \textit{The two different structs can be described in 
602 different compilation units to 
603 facilitate DWARF space compression 
604 (see Appendix \refersec{app:usingcompilationunits}).}
605
606 \subsection{Interface Type Entries}
607 \label{chap:interfacetypeentries}
608
609 \textit{The Java language defines "interface" types. An interface
610 in Java is similar to a C++ or Java class with only abstract
611 methods and constant data members.}
612
613 Interface types are represented by debugging information
614 entries with the 
615 tag \livetarg{chap:DWTAGinterfacetype}{DW\_TAG\_interface\_type}.
616
617 An interface type entry has a DW\_AT\_name attribute, whose
618 value is a null-terminated string containing the type name
619 as it appears in the source program.
620
621 The members of an interface are represented by debugging
622 information entries that are owned by the interface type
623 entry and that appear in the same order as the corresponding
624 declarations in the source program.
625
626 \subsection{Derived or Extended Structs, Classes and Interfaces}
627 \label{chap:derivedorextendedstructsclasesandinterfaces}
628
629 \textit{In C++, a class (or struct) may be ``derived from'' or be a
630 ``subclass of'' another class. In Java, an interface may ``extend''
631 one or more other interfaces, and a class may "extend" another
632 class and/or "implement" one or more interfaces. All of these
633 relationships may be described using the following. Note that
634 in Java, the distinction between extends and implements is
635 implied by the entities at the two ends of the relationship.}
636
637 A class type or interface type entry that describes a
638 derived, extended or implementing class or interface owns
639 debugging information entries describing each of the classes
640 or interfaces it is derived from, extending or implementing,
641 respectively, ordered as they were in the source program. Each
642 such entry has the 
643 tag \livetarg{chap:DWTAGinheritance}{DW\_TAG\_inheritance}.
644
645 An inheritance entry has a DW\_AT\_type attribute whose value is
646 a reference to the debugging information entry describing the
647 class or interface from which the parent class or structure
648 of the inheritance entry is derived, extended or implementing.
649
650 An inheritance entry for a class that derives from or extends
651 another class or struct also has a DW\_AT\_data\_member\_location
652 attribute, whose value describes the location of the beginning
653 of the inherited type relative to the beginning address of the
654 derived class. If that value is a constant, it is the offset
655 in bytes from the beginning of the class to the beginning of
656 the inherited type. Otherwise, the value must be a location
657 description. In this latter case, the beginning address of
658 the derived class is pushed on the expression stack before
659 the location description is evaluated and the result of the
660 evaluation is the location of the inherited type.
661
662 \textit{The interpretation of the value of this attribute for
663 inherited types is the same as the interpretation for data
664 members 
665 (see Section \refersec{chap:datamemberentries}).  }
666
667 An inheritance entry may have a
668 DW\_AT\_accessibility attribute. If no accessibility attribute
669 is present, private access is assumed for an entry of a class
670 and public access is assumed for an entry of an interface,
671 struct or union.
672
673 If the class referenced by the inheritance entry serves
674 as a C++ virtual base class, the inheritance entry has a
675 DW\_AT\_virtuality attribute.
676
677 \textit{For a C++ virtual base, the data member location attribute
678 will usually consist of a non-trivial location description.}
679
680 \subsection{Access Declarations}
681 \label{chap:accessdeclarations}
682
683 \textit{In C++, a derived class may contain access declarations that
684 change the accessibility of individual class members from the
685 overall accessibility specified by the inheritance declaration.
686 A single access declaration may refer to a set of overloaded
687 names.}
688
689 If a derived class or structure contains access declarations,
690 each such declaration may be represented by a debugging
691 information entry with the tag 
692 \livetarg{chap:DWTAGaccessdeclaration}{DW\_TAG\_access\_declaration}. 
693 Each
694 such entry is a child of the class or structure type entry.
695
696 An access declaration entry has a DW\_AT\_name attribute, whose
697 value is a null-terminated string representing the name used
698 in the declaration in the source program, including any class
699 or structure qualifiers.
700
701 An access declaration entry also has a DW\_AT\_accessibility
702 attribute describing the declared accessibility of the named
703 entities.
704
705
706 \subsection{Friends}
707 \label{chap:friends}
708
709 Each ``friend'' declared by a structure, union or class
710 type may be represented by a debugging information entry
711 that is a child of the structure, union or class type entry;
712 the friend entry has the 
713 tag \livetarg{chap:DWTAGfriend}{DW\_TAG\_friend}.
714
715 A friend entry has a DW\_AT\_friend attribute, whose value is
716 a reference to the debugging information entry describing
717 the declaration of the friend.
718
719
720 \subsection{Data Member Entries}
721 \label{chap:datamemberentries}
722
723 A data member (as opposed to a member function) is
724 represented by a debugging information entry with the 
725 tag \livetarg{chap:DWTAGmember}{DW\_TAG\_member}. 
726 The member entry for a named member has
727 a DW\_AT\_name attribute whose value is a null-terminated
728 string containing the member name as it appears in the source
729 program. If the member entry describes an anonymous union, the
730 name attribute is omitted or consists of a single zero byte.
731
732 The data member entry has a DW\_AT\_type attribute to denote
733 the type of that member.
734
735 A data member entry may have a DW\_AT\_accessibility
736 attribute. If no accessibility attribute is present, private
737 access is assumed for an entry of a class and public access
738 is assumed for an entry of a structure, union, or interface.
739
740 A data member entry may have a DW\_AT\_mutable attribute,
741 which is a flag. This attribute indicates whether the data
742 member was declared with the mutable storage class specifier.
743
744 The beginning of a data member is described relative to
745 the beginning of the object in which it is immediately
746 contained. In general, the beginning is characterized by
747 both an address and a bit offset within the byte at that
748 address. When the storage for an entity includes all of
749 the bits in the beginning byte, the beginning bit offset is
750 defined to be zero.
751
752 Bit offsets in DWARF use the bit numbering and direction
753 conventions that are appropriate to the current language on
754 the target system.
755
756 The member entry corresponding to a data member that is
757 defined in a structure, union or class may have either a
758 DW\_AT\_data\_member\_location attribute or a DW\_AT\_data\_bit\_offset
759 attribute. If the beginning of the data member is the same as
760 the beginning of the containing entity then neither attribute
761 is required.
762
763 For a DW\_AT\_data\_member\_location attribute there are two cases:
764
765 \begin{enumerate}[1.]
766
767 \item If the value is an integer constant, it is the offset
768 in bytes from the beginning of the containing entity. If
769 the beginning of the containing entity has a non-zero bit
770 offset then the beginning of the member entry has that same
771 bit offset as well.
772
773 \item Otherwise, the value must be a location description. In
774 this case, the beginning of the containing entity must be byte
775 aligned. The beginning address is pushed on the DWARF stack
776 before the location description is evaluated; the result of
777 the evaluation is the base address of the member entry.
778
779 \textit{The push on the DWARF expression stack of the base address of
780 the containing construct is equivalent to execution of the
781 DW\_OP\_push\_object\_address operation 
782 (see Section \refersec{chap:stackoperations});
783 DW\_OP\_push\_object\_address therefore is not needed at the
784 beginning of a location description for a data member. The
785 result of the evaluation is a location--either an address or
786 the name of a register, not an offset to the member.}
787
788 \textit{A DW\_AT\_data\_member\_location attribute that has the form of a
789 location description is not valid for a data member contained
790 in an entity that is not byte aligned because DWARF operations
791 do not allow for manipulating or computing bit offsets.}
792
793 \end{enumerate}
794
795 For a DW\_AT\_data\_bit\_offset attribute, the value is an integer
796 constant 
797 (see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
798 that specifies the number of bits
799 from the beginning of the containing entity to the beginning
800 of the data member. This value must be greater than or equal
801 to zero, but is not limited to less than the number of bits
802 per byte.
803
804 If the size of a data member is not the same as the size
805 of the type given for the data member, the data member has
806 either a DW\_AT\_byte\_size or a DW\_AT\_bit\_size attribute whose
807 integer constant value 
808 (see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
809 is the amount
810 of storage needed to hold the value of the data member.
811
812 \textit{C and C++ bit fields typically require the use of the
813 DW\_AT\_data\_bit\_offset and DW\_AT\_bit\_size attributes.}
814
815 \textit{This Standard uses the following bit numbering and direction
816 conventions in examples. These conventions are for illustrative
817 purposes and other conventions may apply on particular
818 architectures.}
819
820
821 \begin{itemize}
822 \item \textit{For big\dash endian architectures, bit offsets are
823 counted from high-order to low\dash order bits within a byte (or
824 larger storage unit); in this case, the bit offset identifies
825 the high\dash order bit of the object.}
826
827 \item \textit{For little\dash endian architectures, bit offsets are
828 counted from low\dash order to high\dash order bits within a byte (or
829 larger storage unit); in this case, the bit offset identifies
830 the low\dash order bit of the object.}
831 \end{itemize}
832
833
834 \textit{In either case, the bit so identified is defined as the beginning of the object.}
835
836 \textit{For example, take one possible representation of the following C structure definition in both big\dash and little\dash endian byte orders:}
837
838 \begin{lstlisting}
839 struct S {
840     int j:5;
841     int k:6;
842     int m:5;
843     int n:8;
844 };
845 \end{lstlisting}
846
847 \textit{The following diagrams show the structure layout
848 and data bit offsets for example big\dash\   and little\dash endian
849 architectures, respectively. Both diagrams show a structure
850 that begins at address A and whose size is four bytes. Also,
851 high order bits are to the left and low order bits are to
852 the right.}
853
854 \textit{Big\dash Endian Data Bit Offsets:}
855
856 \begin{verbatim}
857     j:0
858     k:5
859     m:11
860     n:16
861
862     Addresses increase ->
863     |       A       |     A + 1     |    A + 2      |    A + 3      | 
864
865     Data bit offsets increase ->
866     +---------------+---------------+---------------+---------------+
867     |0     4|5         10|11      15|16           23|24           31|
868     |   j   |     k      | m        |        n      |       <pad>   |
869     |       |            |          |               |               | 
870     +---------------------------------------------------------------+ 
871 \end{verbatim}
872
873 \textit{Little\dash  Endian Data Bit Offsets:}
874 \begin{verbatim}
875     j:0
876     k:5
877     m:11
878     n:16
879                                                <- Addresses increase
880     |       A       |     A + 1     |    A + 2      |    A + 3      | 
881
882                                         <-  Data bit offsets increase 
883
884     +---------------+---------------+---------------+---------------+
885     |31           24|23           16|15     11|10       5|4        0|
886     |     <pad>     |        n      |    m    |    k     |     j    |
887     |               |               |         |          |          |
888     +---------------------------------------------------------------+
889
890 \end{verbatim}
891
892 \textit{Note that data member bit offsets in this example are the
893 same for both big\dash\ and little\dash endian architectures even
894 though the fields are allocated in different directions
895 (high\dash order to low-order versus low\dash order to high\dash order);
896 the bit naming conventions for memory and/or registers of
897 the target architecture may or may not make this seem natural.}
898
899 \textit{For a more extensive example showing nested and packed records
900 and arrays, see 
901 Appendix \refersec{app:pascalexample}.}
902
903 \textit{Attribute DW\_AT\_data\_bit\_offset is new in DWARF Version 4 and
904 is also used for base types 
905 (see Section \refersec{chap:basetypeentries}). 
906 It replaces the
907 attributes DW\-\_AT\-\_bit\-\_offset and DW\-\_AT\-\_byte\-\_size when used to
908 identify the beginning of bit field data members as defined
909 in DWARF V3 and earlier. The earlier attributes are defined
910 in a manner suitable for bit field members on big-endian
911 architectures but which is either awkward or incomplete for
912 use on little-endian architectures.  (DW\-\_AT\-\_byte\-\_size also
913 has other uses that are not affected by this change.)}
914
915 \textit{The DW\-\_AT\-\_byte\-\_size, DW\-\_AT\-\_bit\-\_size and 
916 DW\-\_AT\-\_bit\-\_offset
917 attribute combination is deprecated for data members in DWARF
918 Version 4, but implementations may continue to support this
919 use for compatibility.}
920
921 \textit{The DWARF Version 3 definitions of these attributes are
922 as follows.}
923
924 \begin{myindentpara}{1cm}
925 \textit{If the data member entry describes a bit field, then that
926 entry has the following attributes:}
927
928 \begin{itemize}
929 \item \textit{A DW\_AT\_byte\_size attribute whose value (see Section
930 2.19) is the number of bytes that contain an instance of the
931 bit field and any padding bits.}
932
933 \textit{The byte size attribute may be omitted if the size of the
934 object containing the bit field can be inferred from the type
935 attribute of the data member containing the bit field.}
936
937 \item \textit{A DW\_AT\_bit\_offset attribute whose value (see Section
938 2.19) is the number of bits to the left of the leftmost
939 (most significant) bit of the bit field value.}
940
941 \item \textit{A DW\_AT\_bit\_size attribute whose value (see Section
942 2.19) is the number of bits occupied by the bit field value.}
943
944 \end{itemize}
945
946 \textit{The location description for a bit field calculates the address
947 of an anonymous object containing the bit field. The address
948 is relative to the structure, union, or class that most closely
949 encloses the bit field declaration. The number of bytes in this
950 anonymous object is the value of the byte size attribute of
951 the bit field. The offset (in bits) from the most significant
952 bit of the anonymous object to the most significant bit of
953 the bit field is the value of the bit offset attribute.}
954 \end{myindentpara}
955
956
957 \textit{Diagrams similar to the above that show the use of the
958 DW\-\_AT\-\_byte\-\_size, DW\-\_AT\-\_bit\-\_size and DW\-\_AT\-\_bit\-\_offset attribute
959 combination may be found in the DWARF Version 3 Standard.}
960
961 \textit{In comparing DWARF Versions 3 and 4, note that DWARF V4
962 defines the following combinations of attributes:}
963
964 \begin{itemize}
965 \item \textit{either DW\-\_AT\-\_data\-\_member\-\_location or
966 DW\-\_AT\-\_data\-\_bit\-\_offset (to specify the beginning of the
967 data member)}
968
969 % FIXME: the indentation of the following line is suspect.
970 \textit{optionally together with}
971
972 \item  \textit{either DW\_AT\_byte\_size or DW\-\_AT\-\_bit\-\_size (to
973 specify the size of the data member)}
974
975 \end{itemize}
976
977 \textit{DWARF V3 defines the following combinations}
978
979 \begin{itemize}
980 \item \textit{DW\_AT\_data\_member\_location (to specify the beginning
981 of the data member, except this specification is only partial
982 in the case of a bit field) }
983
984 % FIXME: the indentation of the following line is suspect.
985 \textit{optionally together with}
986
987 \item \textit{DW\_AT\_byte\_size, DW\-\_AT\-\_bit\-\_size and DW\-\_AT\_bit\_offset
988 (to further specify the beginning of a bit field data member
989 as well as specify the size of the data member) }
990 \end{itemize}
991
992 \subsection{Member Function Entries}
993 \label{chap:memberfunctionentries}
994
995 A member function is represented by a debugging information
996 entry with the tag DW\_TAG\_subprogram. The member function entry
997 may contain the same attributes and follows the same rules
998 as non\dash member global subroutine entries 
999 (see Section \refersec{chap:subroutineandentrypointentries}).
1000
1001 A member function entry may have a DW\_AT\_accessibility
1002 attribute. If no accessibility attribute is present, private
1003 access is assumed for an entry of a class and public access
1004 is assumed for an entry of a structure, union or interface.
1005
1006 If the member function entry describes a virtual function,
1007 then that entry has a DW\-\_AT\-\_virtuality attribute.
1008
1009 If the member function entry describes an explicit member
1010 function, then that entry has a DW\-\_AT\-\_explicit attribute.
1011
1012 An entry for a virtual function also has a
1013 DW\_AT\_vtable\_elem\_location attribute whose value contains
1014 a location description yielding the address of the slot
1015 for the function within the virtual function table for the
1016 enclosing class. The address of an object of the enclosing
1017 type is pushed onto the expression stack before the location
1018 description is evaluated.
1019
1020 If the member function entry describes a non\dash static member
1021 function, then that entry has a DW\_AT\_object\_pointer attribute
1022 whose value is a reference to the formal parameter entry
1023 that corresponds to the object for which the function is
1024 called. The name attribute of that formal parameter is defined
1025 by the current language (for example, this for C++ or self
1026 for Objective C and some other languages). That parameter
1027 also has a DW\_AT\_artificial attribute whose value is true.
1028
1029 Conversely, if the member function entry describes a static
1030 member function, the entry does not have a DW\_AT\_object\_pointer
1031 attribute.
1032
1033 If the member function entry describes a non\dash static member
1034 function that has a const\dash volatile qualification, then
1035 the entry describes a non\dash static member function whose
1036 object formal parameter has a type that has an equivalent
1037 const\dash volatile qualification.
1038
1039 If a subroutine entry represents the defining declaration
1040 of a member function and that definition appears outside of
1041 the body of the enclosing class declaration, the subroutine
1042 entry has a DW\_AT\_specification attribute, whose value is
1043 a reference to the debugging information entry representing
1044 the declaration of this function member. The referenced entry
1045 will be a child of some class (or structure) type entry.
1046
1047 Subroutine entries containing the DW\_AT\_specification
1048 attribute do not need to duplicate information provided
1049 by the declaration entry referenced by the specification
1050 attribute. In particular, such entries do not need to contain
1051 attributes for the name or return type of the function member
1052 whose definition they represent.
1053
1054 \subsection{Class Template Instantiations}
1055 \label{chap:classtemplateinstantiations}
1056
1057 \textit{In C++ a class template is a generic definition of a class
1058 type that may be instantiated when an instance of the class
1059 is declared or defined. The generic description of the
1060 class may include both parameterized types and parameterized
1061 constant values. DWARF does not represent the generic template
1062 definition, but does represent each instantiation.}
1063
1064 A class template instantiation is represented by a
1065 debugging information entry with the tag DW\_TAG\_class\_type,
1066 DW\_TAG\_structure\_type or DW\_TAG\_union\_type. With five
1067 exceptions, such an entry will contain the same attributes
1068 and have the same types of child entries as would an entry
1069 for a class type defined explicitly using the instantiation
1070 types and values. The exceptions are:
1071
1072 \begin{enumerate}[1.]
1073 \item Each formal parameterized type declaration appearing in the
1074 template definition is represented by a debugging information
1075 entry with the tag DW\_TAG\_template\_type\_parameter. Each
1076 such entry may have a DW\_AT\_name attribute, whose value is
1077 a null\dash terminated string containing the name of the formal
1078 type parameter as it appears in the source program. The
1079 template type parameter entry also has a DW\_AT\_type attribute
1080 describing the actual type by which the formal is replaced
1081 for this instantiation.
1082
1083 \item Each formal parameterized value declaration appearing in the
1084 template definition is represented by a debugging information
1085 entry with the 
1086 tag \livetarg{chap:DWTAGtemplatevalueparameter}{DW\_TAG\_template\_value\_parameter}. 
1087 Each
1088 such entry may have a DW\_AT\_name attribute, whose value is
1089 a null\dash terminated string containing the name of the formal
1090 value parameter as it appears in the source program. The
1091 template value parameter entry also has a DW\_AT\_type attribute
1092 describing the type of the parameterized value. Finally,
1093 the template value parameter entry has a DW\_AT\_const\_value
1094 attribute, whose value is the actual constant value of the
1095 value parameter for this instantiation as represented on the
1096 target architecture.
1097
1098 \item The class type entry and each of its child entries references
1099 a template type parameter entry in any circumstance where the
1100 source template definition references a formal parameterized
1101 type. Similarly, the class type entry and each of its child
1102 entries references a template value parameter entry in any
1103 circumstance where the source template definition references
1104 a formal parameterized value.
1105
1106 \item If the compiler has generated a special compilation unit to
1107 hold the template instantiation and that special compilation
1108 unit has a different name from the compilation unit containing
1109 the template definition, the name attribute for the debugging
1110 information entry representing the special compilation unit
1111 should be empty or omitted.
1112
1113 \item If the class type entry representing the template
1114 instantiation or any of its child entries contains declaration
1115 coordinate attributes, those attributes should refer to
1116 the source for the template definition, not to any source
1117 generated artificially by the compiler.
1118 \end{enumerate}
1119
1120
1121 \subsection{Variant Entries}
1122 \label{chap:variantentries}
1123
1124 A variant part of a structure is represented by a debugging
1125 information entry with the 
1126 tag \livetarg{chap:DWTAGvariantpart}{DW\_TAG\_variant\_part} and is
1127 owned by the corresponding structure type entry.
1128
1129 If the variant part has a discriminant, the discriminant is
1130 represented by a separate debugging information entry which
1131 is a child of the variant part entry. This entry has the form
1132 of a structure data member entry. The variant part entry will
1133 have a DW\_AT\_discr attribute whose value is a reference to
1134 the member entry for the discriminant.
1135
1136 If the variant part does not have a discriminant (tag field),
1137 the variant part entry has a DW\_AT\_type attribute to represent
1138 the tag type.
1139
1140 Each variant of a particular variant part is represented by
1141 a debugging information entry with the 
1142 tag \livetarg{chap:DWTAGvariant}{DW\_TAG\_variant}
1143 and is a child of the variant part entry. The value that
1144 selects a given variant may be represented in one of three
1145 ways. The variant entry may have a DW\_AT\_discr\_value attribute
1146 whose value represents a single case label. The value of this
1147 attribute is encoded as an LEB128 number. The number is signed
1148 if the tag type for the variant part containing this variant
1149 is a signed type. The number is unsigned if the tag type is
1150 an unsigned type.
1151
1152 Alternatively, the variant entry may contain a DW\_AT\_discr\_list
1153 attribute, whose value represents a list of discriminant
1154 values. This list is represented by any of the block forms and
1155 may contain a mixture of case labels and label ranges. Each
1156 item on the list is prefixed with a discriminant value
1157 descriptor that determines whether the list item represents
1158 a single label or a label range. A single case label is
1159 represented as an LEB128 number as defined above for the
1160 DW\_AT\_discr\_value attribute. A label range is represented by
1161 two LEB128 numbers, the low value of the range followed by the
1162 high value. Both values follow the rules for signedness just
1163 described. The discriminant value descriptor is an integer
1164 constant that may have one of the values given in 
1165 Figure \refersec{fig:discriminantdescriptorvalues}.
1166
1167 \begin{figure}[here]
1168 \autorows[0pt]{c}{1}{l}{
1169 \addtoindex{DW\_DSC\_label},
1170 \addtoindex{DW\_DSC\_range}
1171 }
1172 \caption{Discriminant descriptor values}\label{fig:discriminantdescriptorvalues}
1173 \end{figure}
1174
1175 If a variant entry has neither a DW\_AT\_discr\_value
1176 attribute nor a DW\_AT\_discr\_list attribute, or if it has
1177 a DW\_AT\_discr\_list attribute with 0 size, the variant is a
1178 default variant.
1179
1180 The components selected by a particular variant are represented
1181 by debugging information entries owned by the corresponding
1182 variant entry and appear in the same order as the corresponding
1183 declarations in the source program.
1184
1185 \section{Condition Entries}
1186 \label{chap:conditionentries}
1187
1188 \textit{COBOL has the notion of a ``level\dash 88 condition'' that
1189 associates a data item, called the conditional variable, with
1190 a set of one or more constant values and/or value ranges.
1191 Semantically, the condition is ‛true’ if the conditional
1192 variable's value matches any of the described constants,
1193 and the condition is ‛false’ otherwise.}
1194
1195 The \livetarg{chap:DWTAGcondition}{DW\_TAG\_condition} debugging information entry
1196 describes a
1197 logical condition that tests whether a given data item’s
1198 value matches one of a set of constant values. If a name
1199 has been given to the condition, the condition entry has a
1200 DW\_AT\_name attribute whose value is a null\dash terminated string
1201 giving the condition name as it appears in the source program.
1202
1203 The condition entry's parent entry describes the conditional
1204 variable; normally this will be a DW\_TAG\_variable,
1205 DW\_TAG\_member or DW\_TAG\_formal\_parameter entry. If the parent
1206 entry has an array type, the condition can test any individual
1207 element, but not the array as a whole. The condition entry
1208 implicitly specifies a “comparison type” that is the
1209 type of an array element if the parent has an array type;
1210 otherwise it is the type of the parent entry.
1211
1212 The condition entry owns DW\_TAG\_constant and/or
1213 DW\_TAG\_subrange\_type entries that describe the constant
1214 values associated with the condition. If any child entry has
1215 a DW\_AT\_type attribute, that attribute should describe a type
1216 compatible with the comparison type (according to the source
1217 language); otherwise the child’s type is the same as the
1218 comparison type.
1219
1220 \textit{For conditional variables with alphanumeric types, COBOL
1221 permits a source program to provide ranges of alphanumeric
1222 constants in the condition. Normally a subrange type entry
1223 does not describe ranges of strings; however, this can be
1224 represented using bounds attributes that are references to
1225 constant entries describing strings. A subrange type entry may
1226 refer to constant entries that are siblings of the subrange
1227 type entry.}
1228
1229
1230 \section{Enumeration Type Entries}
1231 \label{chap:enumerationtypeentries}
1232
1233 \textit{An “enumeration type” is a scalar that can assume one of
1234 a fixed number of symbolic values.}
1235
1236 An enumeration type is represented by a debugging information
1237 entry with the tag 
1238 \livetarg{chap:DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}.
1239
1240 If a name has been given to the enumeration type in the source
1241 program, then the corresponding enumeration type entry has
1242 a DW\_AT\_name attribute whose value is a null\dash terminated
1243 string containing the enumeration type name as it appears
1244 in the source program. This entry also has a DW\_AT\_byte\_size
1245 attribute whose integer constant value is the number of bytes
1246 required to hold an instance of the enumeration.
1247
1248 The enumeration type entry may have a DW\_AT\_type attribute
1249 which refers to the underlying data type used to implement
1250 the enumeration.
1251
1252 If an enumeration type has type safe semantics such that
1253
1254 \begin{enumerate}[1.]
1255 \item Enumerators are contained in the scope of the enumeration type, and/or
1256
1257 \item Enumerators are not implicitly converted to another type
1258 \end{enumerate}
1259
1260 then the enumeration type entry may have a DW\_AT\_enum\_class
1261 attribute, which is a flag. In a language that offers only
1262 one kind of enumeration declaration, this attribute is not
1263 required.
1264
1265 \textit{In C or C++, the underlying type will be the appropriate
1266 integral type determined by the compiler from the properties of
1267 the enumeration literal values. A C++ type declaration written
1268 using enum class declares a strongly typed enumeration and
1269 is represented using DW\_TAG\_enumeration\_type in combination
1270 with DW\_AT\_enum\_class.}
1271
1272 Each enumeration literal is represented by a debugging
1273 information entry with the 
1274 tag \livetarg{chap:DWTAGenumerator}{DW\_TAG\_enumerator}. 
1275 Each
1276 such entry is a child of the enumeration type entry, and the
1277 enumerator entries appear in the same order as the declarations
1278 of the enumeration literals in the source program.
1279
1280 Each enumerator entry has a DW\_AT\_name attribute, whose
1281 value is a null\dash terminated string containing the name of the
1282 enumeration literal as it appears in the source program. Each
1283 enumerator entry also has a DW\_AT\_const\_value attribute,
1284 whose value is the actual numeric value of the enumerator as
1285 represented on the target system.
1286
1287
1288 If the enumeration type occurs as the description of a
1289 dimension of an array type, and the stride for that dimension
1290 is different than what would otherwise be determined, then
1291 the enumeration type entry has either a DW\_AT\_byte\_stride
1292 or DW\_AT\_bit\_stride attribute which specifies the separation
1293 between successive elements along the dimension as described
1294 in 
1295 Section \refersec{chap:visibilityofdeclarations}. 
1296 The value of the DW\_AT\_bit\_stride attribute
1297 is interpreted as bits and the value of the DW\_AT\_byte\_stride
1298 attribute is interpreted as bytes.
1299
1300
1301 \section{Subroutine Type Entries}
1302 \label{chap:subroutinetypeentries}
1303
1304 It is possible in C to declare pointers to subroutines
1305 that return a value of a specific type. In both C and C++,
1306 it is possible to declare pointers to subroutines that not
1307 only return a value of a specific type, but accept only
1308 arguments of specific types. The type of such pointers would
1309 be described with a ``pointer to'' modifier applied to a
1310 user\dash defined type.
1311
1312 A subroutine type is represented by a debugging information
1313 entry with the 
1314 tag \livetarg{chap:DWTAGsubroutinetype}{DW\_TAG\_subroutine\_type}. 
1315 If a name has
1316 been given to the subroutine type in the source program,
1317 then the corresponding subroutine type entry has a DW\_AT\_name
1318 attribute whose value is a null\dash terminated string containing
1319 the subroutine type name as it appears in the source program.
1320
1321 If the subroutine type describes a function that returns
1322 a value, then the subroutine type entry has a DW\_AT\_type
1323 attribute to denote the type returned by the subroutine. If
1324 the types of the arguments are necessary to describe the
1325 subroutine type, then the corresponding subroutine type
1326 entry owns debugging information entries that describe the
1327 arguments. These debugging information entries appear in the
1328 order that the corresponding argument types appear in the
1329 source program.
1330
1331 In C there is a difference between the types of functions
1332 declared using function prototype style declarations and
1333 those declared using non\dash prototype declarations.
1334
1335 A subroutine entry declared with a function prototype style
1336 declaration may have a DW\_AT\_prototyped attribute, which is
1337 a flag.
1338
1339 Each debugging information entry owned by a subroutine
1340 type entry has a tag whose value has one of two possible
1341 interpretations:
1342
1343 \begin{enumerate}[1.]
1344 \item The formal parameters of a parameter list (that have a
1345 specific type) are represented by a debugging information entry
1346 with the tag DW\_TAG\_formal\_parameter. Each formal parameter
1347 entry has a DW\_AT\_type attribute that refers to the type of
1348 the formal parameter.
1349
1350 \item The unspecified parameters of a variable parameter list
1351 are represented by a debugging information entry with the
1352 tag DW\_TAG\_unspecified\_parameters.
1353 \end{enumerate}
1354
1355
1356
1357 \section{String Type Entries}
1358 \label{chap:stringtypeentries}
1359
1360
1361 A ``string'' is a sequence of characters that have specific
1362 semantics and operations that separate them from arrays of
1363 characters. Fortran is one of the languages that has a string
1364 type. Note that ``string'' in this context refers to a target
1365 machine concept, not the class string as used in this document
1366 (except for the name attribute).
1367
1368 A string type is represented by a debugging information entry
1369 with the tag \livetarg{chap:DWTAGstringtype}{DW\_TAG\_string\_type}. 
1370 If a name has been given to
1371 the string type in the source program, then the corresponding
1372 string type entry has a DW\_AT\_name attribute whose value is
1373 a null\dash terminated string containing the string type name as
1374 it appears in the source program.
1375
1376 The string type entry may have a DW\_AT\_string\_length attribute
1377 whose value is a location description yielding the location
1378 where the length of the string is stored in the program. The
1379 string type entry may also have a DW\_AT\_byte\_size attribute
1380 or DW\_AT\_bit\_size attribute, whose value 
1381 (see Section \refersec{chap:byteandbitsizes}) 
1382 is the size of the data to be retrieved from the location
1383 referenced by the string length attribute. If no (byte or bit)
1384 size attribute is present, the size of the data to be retrieved
1385 is the same as the size of an address on the target machine.
1386
1387 If no string length attribute is present, the string type
1388 entry may have a DW\_AT\_byte\_size attribute or DW\_AT\_bit\_size
1389 attribute, whose value 
1390 (see Section \refersec{chap:byteandbitsizes}) 
1391 is the amount of
1392 storage needed to hold a value of the string type.
1393
1394
1395 \section{Set Type Entries}
1396 \label{chap:settypeentries}
1397
1398 \textit{Pascal provides the concept of a “set,” which represents
1399 a group of values of ordinal type.}
1400
1401 A set is represented by a debugging information entry with
1402 the tag \livetarg{chap:DWTAGsettype}{DW\_TAG\_set\_type}. 
1403 If a name has been given to the
1404 set type, then the set type entry has a DW\_AT\_name attribute
1405 whose value is a null\dash terminated string containing the
1406 set type name as it appears in the source program.
1407
1408 The set type entry has a DW\_AT\_type attribute to denote the
1409 type of an element of the set.
1410
1411 If the amount of storage allocated to hold each element of an
1412 object of the given set type is different from the amount of
1413 storage that is normally allocated to hold an individual object
1414 of the indicated element type, then the set type entry has
1415 either a DW\_AT\_byte\_size attribute, or DW\_AT\_bit\_size attribute
1416 whose value (see Section \refersec{chap:byteandbitsizes}) is
1417 the amount of storage needed to hold a value of the set type.
1418
1419
1420 \section{Subrange Type Entries}
1421 \label{chap:subrangetypeentries}
1422
1423 \textit{Several languages support the concept of a ``subrange''
1424 type object. These objects can represent a subset of the
1425 values that an object of the basis type for the subrange can
1426 represent. Subrange type entries may also be used to represent
1427 the bounds of array dimensions.}
1428
1429 A subrange type is represented by a debugging information
1430 entry with the 
1431 tag \livetarg{chap:DWTAGsubrangetype}{DW\_TAG\_subrange\_type}. 
1432 If a name has been
1433 given to the subrange type, then the subrange type entry
1434 has a DW\_AT\_name attribute whose value is a null\dash terminated
1435 string containing the subrange type name as it appears in
1436 the source program.
1437
1438 The subrange entry may have a DW\_AT\_type attribute to describe
1439 the type of object, called the basis type, of whose values
1440 this subrange is a subset.
1441
1442 If the amount of storage allocated to hold each element of an
1443 object of the given subrange type is different from the amount
1444 of storage that is normally allocated to hold an individual
1445 object of the indicated element type, then the subrange
1446 type entry has a DW\_AT\_byte\_size attribute or DW\_AT\_bit\_size
1447 attribute, whose value 
1448 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1449 is the amount of
1450 storage needed to hold a value of the subrange type.
1451
1452 The subrange entry may have a DW\_AT\_threads\_scaled attribute,
1453 which is a flag. If present, this attribute indicates whether
1454 this subrange represents a UPC array bound which is scaled
1455 by the runtime THREADS value (the number of UPC threads in
1456 this execution of the program).
1457
1458 \textit{This allows the representation of a UPC shared array such as}
1459
1460 \begin{lstlisting}
1461 int shared foo[34*THREADS][10][20];
1462 \end{lstlisting}
1463
1464 The subrange entry may have the attributes DW\_AT\_lower\_bound
1465 and DW\_AT\_upper\_bound to specify, respectively, the lower
1466 and upper bound values of the subrange. The DW\_AT\_upper\_bound
1467 attribute may be replaced by a DW\_AT\_count attribute, whose
1468 value describes the number of elements in the subrange rather
1469 than the value of the last element. The value of each of
1470 these attributes is determined as described in 
1471 Section \refersec{chap:staticanddynamicvaluesofattributes}.
1472
1473 If the lower bound value is missing, the value is assumed to
1474 be a language\dash dependent default constant. The default lower
1475 bound is 0 for C, C++, D, Java, Objective C, Objective C++,
1476 Python, and UPC. The default lower bound is 1 for Ada, COBOL,
1477 Fortran, Modula\dash 2, Pascal and PL/I.
1478
1479 \textit{No other default lower bound values are currently defined.}
1480
1481 If the upper bound and count are missing, then the upper bound value is 
1482 \textit{unknown}.
1483
1484 If the subrange entry has no type attribute describing the
1485 basis type, the basis type is assumed to be the same as
1486 the object described by the lower bound attribute (if it
1487 references an object). If there is no lower bound attribute,
1488 or that attribute does not reference an object, the basis type
1489 is the type of the upper bound or count attribute (if either
1490 of them references an object). If there is no upper bound or
1491 count attribute, or neither references an object, the type is
1492 assumed to be the same type, in the source language of the
1493 compilation unit containing the subrange entry, as a signed
1494 integer with the same size as an address on the target machine.
1495
1496 If the subrange type occurs as the description of a dimension
1497 of an array type, and the stride for that dimension is
1498 different than what would otherwise be determined, then
1499 the subrange type entry has either a DW\_AT\_byte\_stride or
1500 DW\_AT\_bit\_stride attribute which specifies the separation
1501 between successive elements along the dimension as described
1502 in 
1503 Section \refersec{chap:byteandbitsizes}.
1504
1505 \textit{Note that the stride can be negative.}
1506
1507 \section{Pointer to Member Type Entries}
1508 \label{chap:pointertomembertypeentries}
1509
1510 \textit{In C++, a pointer to a data or function member of a class or
1511 structure is a unique type.}
1512
1513 A debugging information entry representing the type of an
1514 object that is a pointer to a structure or class member has
1515 the tag \livetarg{chap:DWTAGptrtomembertype}{DW\_TAG\_ptr\_to\_member\_type}.
1516
1517 If the pointer to member type has a name, the pointer to
1518 member entry has a DW\_AT\_name attribute, whose value is a
1519 null\dash terminated string containing the type name as it appears
1520 in the source program.
1521
1522 The pointer to member entry has a DW\_AT\_type attribute to
1523 describe the type of the class or structure member to which
1524 objects of this type may point.
1525
1526 The pointer to member entry also has a DW\_AT\_containing\_type
1527 attribute, whose value is a reference to a debugging
1528 information entry for the class or structure to whose members
1529 objects of this type may point.
1530
1531 The pointer to member entry has a DW\_AT\_use\_location attribute
1532 whose value is a location description that computes the
1533 address of the member of the class to which the pointer to
1534 member entry points.
1535
1536 \textit{The method used to find the address of a given member of a
1537 class or structure is common to any instance of that class
1538 or structure and to any instance of the pointer or member
1539 type. The method is thus associated with the type entry,
1540 rather than with each instance of the type.}
1541
1542 The DW\_AT\_use\_location description is used in conjunction
1543 with the location descriptions for a particular object of the
1544 given pointer to member type and for a particular structure or
1545 class instance. The DW\_AT\_use\_location attribute expects two
1546 values to be pushed onto the DWARF expression stack before
1547 the DW\_AT\_use\_location description is evaluated. The first
1548 value pushed is the value of the pointer to member object
1549 itself. The second value pushed is the base address of the
1550 entire structure or union instance containing the member
1551 whose address is being calculated.
1552
1553 \textit{For an expression such as}
1554
1555 \begin{lstlisting}
1556     object.*mbr_ptr
1557 \end{lstlisting}
1558 % FIXME: object and mbr\_ptr should be distinguished from italic. See DW4.
1559 \textit{where mbr\_ptr has some pointer to member type, a debugger should:}
1560
1561 \textit{1. Push the value of mbr\_ptr onto the DWARF expression stack.}
1562
1563 \textit{2. Push the base address of object onto the DWARF expression stack.}
1564
1565 \textit{3. Evaluate the DW\_AT\_use\_location description 
1566 given in the type of mbr\_ptr.}
1567
1568 \section{File Type Entries}
1569 \label{chap:filetypeentries}
1570
1571 \textit{Some languages, such as Pascal, provide a data type to represent 
1572 files.}
1573
1574 A file type is represented by a debugging information entry
1575 with the 
1576 \livetarg{chap:DWTAGfiletype}{tag DW\_TAG\_file\_type}. 
1577 If the file type has a name,
1578 the file type entry has a DW\_AT\_name attribute, whose value
1579 is a null\dash terminated string containing the type name as it
1580 appears in the source program.
1581
1582 The file type entry has a DW\_AT\_type attribute describing
1583 the type of the objects contained in the file.
1584
1585 The file type entry also has a DW\_AT\_byte\_size or
1586 DW\_AT\_bit\_size attribute, whose value 
1587 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
1588 is the amount of storage need to hold a value of the file type.
1589
1590 \section{Dynamic Type Properties}
1591 \label{chap:dynamictypeproperties}
1592 \subsection{Data Location}
1593 \label{chap:datalocation}
1594
1595 \textit{Some languages may represent objects using descriptors to hold
1596 information, including a location and/or run\dash time parameters,
1597 about the data that represents the value for that object.}
1598
1599 The DW\_AT\_data\_location attribute may be used with any
1600 type that provides one or more levels of hidden indirection
1601 and/or run\dash time parameters in its representation. Its value
1602 is a location description. The result of evaluating this
1603 description yields the location of the data for an object.
1604 When this attribute is omitted, the address of the data is
1605 the same as the address of the object.
1606
1607 \textit{This location description will typically begin with
1608 DW\_OP\_push\_object\_address which loads the address of the
1609 object which can then serve as a descriptor in subsequent
1610 calculation. For an example using DW\_AT\_data\_location for a
1611 Fortran 90 array, see 
1612 Appendix \refersec{app:fortran90example}.}
1613
1614 \subsection{Allocation and Association Status}
1615 \label{chap:allocationandassociationstatus}
1616
1617 \textit{Some languages, such as Fortran 90, provide types whose values
1618 may be dynamically allocated or associated with a variable
1619 under explicit program control.}
1620
1621 The DW\_AT\_allocated attribute may optionally be used with any
1622 type for which objects of the type can be explicitly allocated
1623 and deallocated. The presence of the attribute indicates that
1624 objects of the type are allocatable and deallocatable. The
1625 integer value of the attribute (see below) specifies whether
1626 an object of the type is currently allocated or not.
1627
1628 The DW\_AT\_associated attribute may optionally be used with
1629 any type for which objects of the type can be dynamically
1630 associated with other objects. The presence of the attribute
1631 indicates that objects of the type can be associated. The
1632 integer value of the attribute (see below) indicates whether
1633 an object of the type is currently associated or not.
1634
1635 While these attributes are defined specifically with Fortran
1636 90 ALLOCATABLE and POINTER types in mind, usage is not limited
1637 to just that language.
1638
1639 The value of these attributes is determined as described in
1640 Section \refersec{chap:staticanddynamicvaluesofattributes}.
1641
1642 A non\dash zero value is interpreted as allocated or associated,
1643 and zero is interpreted as not allocated or not associated.
1644
1645 \textit{For Fortran 90, if the DW\_AT\_associated attribute is present,
1646 the type has the POINTER property where either the parent
1647 variable is never associated with a dynamic object or the
1648 implementation does not track whether the associated object
1649 is static or dynamic. If the DW\_AT\_allocated attribute is
1650 present and the DW\_AT\_associated attribute is not, the type
1651 has the ALLOCATABLE property. If both attributes are present,
1652 then the type should be assumed to have the POINTER property
1653 (and not ALLOCATABLE); the DW\_AT\_allocated attribute may then
1654 be used to indicate that the association status of the object
1655 resulted from execution of an ALLOCATE statement rather than
1656 pointer assignment.}
1657
1658 \textit{For examples using DW\_AT\_allocated for Ada and Fortran 90
1659 arrays, 
1660 see Appendix \refersec{app:aggregateexamples}.}
1661
1662
1663
1664 \section{Template Alias Entries}
1665 \label{chap:templatealiasentries}
1666
1667 A type named using a template alias is represented
1668 by a debugging information entry with the tag
1669 \livetarg{chap:DWTAGtemplatealias}{DW\-\_TAG\-\_template\-\_alias}. 
1670 The template alias entry has a
1671 DW\-\_AT\-\_name attribute whose value is a null\dash terminated string
1672 containing the name of the template alias as it appears in
1673 the source program. The template alias entry also contains a
1674 DW\-\_AT\-\_type attribute whose value is a reference to the type
1675 named by the template alias. The template alias entry has
1676 the following child entries:
1677
1678 \begin{enumerate}[1.]
1679 \item Each formal parameterized type declaration appearing
1680 in the template alias declaration is represented
1681 by a debugging information entry with the tag
1682 DW\-\_TAG\-\_template\-\_type\-\_parameter. Each such entry may have
1683 a DW\_AT\_name attribute, whose value is a null\dash terminated
1684 string containing the name of the formal type parameter as it
1685 appears in the source program. The template type parameter
1686 entry also has a DW\-\_AT\-\_type attribute describing the actual
1687 type by which the formal is replaced for this instantiation.
1688
1689 \item Each formal parameterized value declaration
1690 appearing in the template alias declaration is
1691 represented by a debugging information entry with the tag
1692 DW\-\_TAG\-\_template\-\_value\-\_parameter. Each such entry may have
1693 a DW\-\_AT\-\_name attribute, whose value is a null\dash terminated
1694 string containing the name of the formal value parameter
1695 as it appears in the source program. The template value
1696 parameter entry also has a DW\-\_AT\-\_type attribute describing
1697 the type of the parameterized value. Finally, the template
1698 value parameter entry has a DW\-\_AT\-\_const\-\_value attribute, whose
1699 value is the actual constant value of the value parameter for
1700 this instantiation as represented on the target architecture.
1701 \end{enumerate}
1702