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