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