refclassfixup.py fixes up some class references.
[dwarf-doc.git] / dwarf5 / latexdoc / dataobject.tex
1 \chapter[Data Object and Object List]{Data Object and Object List Entries}
2 \label{chap:dataobjectandobjectlistentries}
3
4 This section presents the debugging information entries that
5 describe individual data objects: variables, parameters and
6 constants, and lists of those objects that may be grouped in
7 a single declaration, such as a common block.
8
9 \section{Data Object Entries}
10 \label{chap:dataobjectentries}
11
12
13 Program variables, formal parameters and constants are
14 represented by debugging information entries with the tags
15 DW\_TAG\_variable, DW\_TAG\_formal\_parameter and DW\_TAG\_constant,
16 respectively.
17
18 \textit{The tag DW\_TAG\_constant is used for languages that
19 have true named constants.}
20
21 The debugging information entry for a program variable,
22 formal parameter or constant may have the following attributes:
23 \begin{enumerate}[1.]
24 \item A DW\_AT\_name attribute, whose value is a null-terminated
25 string, containing the data object name as it appears in the
26 source program.  If a variable entry describes an anonymous
27 union, the name attribute is omitted or consists of a single
28 zero byte.
29
30 \item A DW\_AT\_external attribute, which is a flag, if the name
31 of a variable is visible outside of its enclosing compilation
32 unit.  The definitions of C++ static data members of structures
33 or classes are represented by variable entries flagged as
34 external. Both file static and local variables in C and C++
35 are represented by non-external variable entries.
36
37 \item A DW\_AT\_declaration attribute, which is a flag that
38 indicates whether this entry represents a non-defining
39 declaration of an object.
40
41 \item A DW\_AT\_location attribute, whose value describes the
42 location of a variable or parameter at run-time.  In a variable
43 entry representing the definition of a variable (that is,
44 with no DW\_AT\_declaration attribute) if no location attribute
45 is present, or if the location attribute is present but has
46 an empty location description (as described in Section 2.6),
47 the variable is assumed to exist in the source code but not
48 in the executable program (but see number 10, below).
49
50 In a variable entry representing a non-defining declaration of a variable, the location
51 specified modifies the location specified by the defining declaration and only applies for the
52 scope of the variable entry; if no location is specified, then the location specified in the
53 defining declaration applies.
54 The location of a variable may be further specified with a DW\_AT\_segment attribute, if
55 appropriate.
56
57 \item A DW\_AT\_type attribute describing the type of the variable,
58 constant or formal parameter.
59
60 \item If the variable entry represents the defining declaration
61 for a C++ static data member of a structure, class or union,
62 the entry has a DW\_AT\_specification attribute, whose value is a
63 reference to the debugging information entry representing the
64 declaration of this data member. The referenced entry has the
65 tag DW\_TAG\_member and will be a child of some class, structure
66 or union type entry.  If the variable entry represents a
67 non-defining declaration, DW\_AT\_specification may be used
68 to reference the defining declaration of the variable. If
69 no DW\_AT\_specification attribute is present, the defining
70 declaration may be found as a global definition either in the
71 current compilation unit or in another compilation unit with
72 the DW\_AT\_external attribute.  Variable entries containing
73 the DW\_AT\_specification attribute do not need to duplicate
74 information provided by the declaration entry referenced by
75 the specification attribute. In particular, such variable
76 entries do not need to contain attributes for the name or
77 type of the data member whose definition they represent.
78
79 \item A DW\_AT\_variable\_parameter attribute, which is a flag,
80 if a formal parameter entry represents a parameter whose
81 value in the calling function may be modified by the callee..
82 The absence of this attribute implies that the parameter’s
83 value in the calling function cannot be modified by the callee.
84
85 \item A DW\_AT\_is\_optional attribute, which is a flag, if a
86 parameter entry represents an optional parameter.
87
88 \item A DW\_AT\_default\_value attribute for a formal parameter
89 entry. The value of this attribute is a reference to the
90 debugging information entry for a variable or subroutine,
91 or the value may be a constant. If the attribute form is of
92 class reference, the default value of the parameter is the
93 value of the referenced variable (which may be constant) or
94 the value returned by the referenced subroutine; a reference
95 value of 0 means that no default value has been specified.
96 If the value is of class constant, that constant is interpreted
97 as a default value of the type of the formal parameter.
98
99 \textit{For a constant form there is no way to 
100 express the absence of a default value.}
101
102 \item A DW\_AT\_const\_value attribute for an entry describing a
103 variable or formal parameter whose value is constant and not
104 represented by an object in the address space of the program,
105 or an entry describing a named constant. (Note that such
106 an entry does not have a location attribute.) The value of
107 this attribute may be a string or any of the constant data
108 or data block forms, as appropriate for the representation
109 of the variable’s value. The value is the actual constant
110 value of the variable, represented as it would be on the
111 target architecture.  One way in which a formal parameter
112 with a constant value and no location can arise is for a
113 formal parameter of an inlined subprogram that corresponds
114 to a constant actual parameter of a call that is inlined.
115
116 \item A DW\_AT\_start\_scope attribute if the scope of an
117 object is smaller than (that is, is a subset of the addresses
118 of) the scope most closely enclosing the object. There are
119 two cases:
120 \begin{enumerate}[a)]
121 \item If the scope of the object entry includes all of the
122 containing scope except for a contiguous sequence of bytes at
123 the beginning of that containing scope, then the scope of the
124 object is specified using a value of class constant. If the
125 containing scope is contiguous, the value of this attribute
126 is the offset in bytes of the beginning of the scope for the
127 object from the low pc value of the debugging information
128 entry that defines its scope. If the containing scope
129 is non-contiguous (see Section 2.17.3), the value of this
130 attribute is the offset in bytes of the beginning of the scope
131 for the object from the beginning of the first range list entry
132 that is not a base selection entry or an end of list entry.
133
134 \item Otherwise, the scope of the object is specified using
135 a value of class \livelink{chap:rangelistptr}{rangelistptr}. This value indicates the
136 beginning of a range list (see Section 2.17.3).
137 \end{enumerate}
138
139
140 \textit{The scope of a variable may begin somewhere in the middle of
141 a lexical block in a language that allows executable code in a
142 block before a variable declaration, or where one declaration
143 containing initialization code may change the scope of a
144 subsequent declaration.  For example, in the following C code:}
145
146 \begin{lstlisting}
147 float x = 99.99;
148 int myfunc()
149 {
150     float f = x;
151     float x = 88.99;
152     return 0;
153 }
154 \end{lstlisting}
155
156 \textit{C scoping rules require that the value of the variable x
157 assigned to the variable f in the initialization sequence is
158 the value of the global variable x, rather than the local x,
159 because the scope of the local variable x only starts after
160 the full declarator for the local x.}
161
162 \textit{Due to optimization, the scope of an object may be
163 non-contiguous and require use of a range list even when
164 the containing scope is contiguous. Conversely, the scope of
165 an object may not require its own range list even when the
166 containing scope is non\dash contiguous.}
167
168 \item A DW\_AT\_endianity attribute, whose value is a constant
169 that specifies the endianity of the object. The value of
170 this attribute specifies an ABI\dash defined byte ordering for
171 the value of the object. If omitted, the default endianity
172 of data for the given type is assumed.  The set of values
173 and their meaning for this attribute is given in 
174 Figure \refersec{fig:endianityattributevalues}.
175
176 \begin{figure}[here]
177 \centering
178 \begin{tabular}{lp{9cm}}
179 Name&Meaning\\ \hline
180 DW\_END\_default &  Default endian encoding
181   (equivalent to the absence of a 
182   DW\_AT\_endianity attribute) \\
183 DW\_END\_big & Big\dash endian encoding \\
184 DW\_END\_little& Little-endian encoding \\
185 \end{tabular}
186 \caption{Endianity attribute values}
187 \label{fig:endianityattributevalues}
188 \end{figure}
189
190
191 These represent the default encoding formats as defined by
192 the target architecture’s ABI or processor definition. The
193 exact definition of these formats may differ in subtle ways
194 for different architectures.
195
196
197 \item A DW\_AT\_const\_expr attribute, which is a flag, if a
198 variable entry represents a C++ object declared with the
199 constexpr specifier. This attributes indicates that the
200 variable can be evaluated as a compile\dash time constant.  
201
202 \textit{In C++,
203 a variable declared with constexpr is implicitly const. Such a
204 variable has a DW\_AT\_type attribute whose value is a reference
205 to a debugging information entry}
206
207 \item A DW\_AT\_linkage\_name attribute for a 
208 variable or constant entry as described in 
209 Section \refersec{chap:linkagenames}.
210
211 \end{enumerate}
212
213 FIXME incomplete
214
215
216 \section{Common Block Entries}
217 \label{chap:commonblockentries}
218 A Fortran common block may be described by a debugging
219 information entry with the tag DW\_TAG\_common\_block. The
220 common block entry has a DW\_AT\_name attribute whose value
221 is a null-terminated string containing the common block
222 name as it appears in the source program. It may also have a
223 DW\_AT\_linkage\_name attribute as described in 
224 Section \refersec{chap:linkagenames}. 
225 It
226 also has a DW\_AT\_location attribute whose value describes the
227 location of the beginning of the common block. The common
228 block entry owns debugging information entries describing
229 the variables contained within the common block.
230
231 \section{Namelist Entries}
232 \label{chap:namelistentries}
233 \textit{At least one language, Fortran 90, has the concept of a
234 namelist. A namelist is an ordered list of the names of some
235 set of declared objects. The namelist object itself may be used
236 as a replacement for the list of names in various contexts.}
237
238 A namelist is represented by a debugging information entry
239 with the tag DW\_TAG\_namelist. If the namelist itself has a
240 name, the namelist entry has a DW\_AT\_name attribute, whose
241 value is a null-terminated string containing the namelist’s
242 name as it appears in the source program.
243
244 Each name that is part of the namelist is represented
245 by a debugging information entry with the tag
246 DW\_TAG\_namelist\_item. Each such entry is a child of the
247 namelist entry, and all of the namelist item entries for a
248 given namelist are ordered as were the list of names they
249 correspond to in the source program.
250
251 Each namelist item entry contains a DW\_AT\_namelist\_item
252 attribute whose value is a reference to the debugging
253 information entry representing the declaration of the item
254 whose name appears in the namelist.
255
256