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