Draft document for Committee review.
[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 
8 \livelink{chap:commonblockentry}{common block}.
9
10 \section{Data Object Entries}
11 \label{chap:dataobjectentries}
12 \addtoindexx{data object entries}
13
14 Program variables, 
15 \addtoindexx{formal parameter entry}
16 formal parameters and constants are
17 represented by debugging information entries with the tags
18 \DWTAGvariableTARG\addtoindexx{variable entry}, 
19 \DWTAGformalparameterTARG\addtoindexx{formal parameter entry} and 
20 \DWTAGconstantTARG\addtoindexx{constant (data) entry},
21 respectively.
22
23 \textit{The tag \DWTAGconstant{} is used for languages that
24 have true named constants.}
25
26 The debugging information entry for a program variable,
27 formal parameter or constant may have the following attributes:
28 \begin{enumerate}[1. ]
29 \item A \DWATname{} attribute,
30 \addtoindexx{name attribute}
31 whose value is a null-terminated string containing the data object 
32 name as it appears in the source program.
33
34 If a variable entry describes an anonymous object (for example
35 an \addtoindex{anonymous union}),
36 the name attribute is omitted or its value consists of a single
37 zero byte.
38
39 \item A \DWATexternalDEFN{} attribute, 
40 \hypertarget{chap:DWATexternalexternalvariable}{}
41 which 
42 \addtoindexx{external attribute}
43 is a \livelink{chap:classflag}{flag}, if the name
44 of a variable is visible outside of its enclosing compilation
45 unit.  
46
47 \textit{The definitions of \addtoindex{C++} static data members 
48 of structures or classes are represented by variable entries 
49 \nolink{flagged} as external. Both file static and local variables 
50 in \addtoindex{C} and \addtoindex{C++} are represented by 
51 non-external variable entries.}
52
53 \item A \DWATdeclaration{} attribute, 
54 \addtoindexx{declaration attribute}
55 which is a \livelink{chap:classflag}{flag} that
56 indicates whether this entry represents a non-defining
57 declaration of an object.
58
59 \item A \DWATlocation{} attribute,
60 \addtoindexx{location attribute}
61 whose value describes the location of a variable or parameter at run-time.
62
63 If no location attribute is present in a variable 
64 entry representing the definition of a variable (that is,
65 \addtoindexx{declaration attribute}
66 with no 
67 \DWATdeclaration{} attribute),
68 or if the location attribute is present but has
69 an empty location description (as described in Section 
70 \refersec{chap:locationdescriptions}),
71 \addtoindexx{unallocated variable}
72 the variable is assumed to exist in the source code but not
73 in the executable program (but see number 10, below).
74
75 In a variable entry representing a non-defining declaration 
76 of a variable, the location specified supersedes the location 
77 specified by the defining declaration but only within the
78 scope of the variable entry; if no location is specified, 
79 then the location specified in the defining declaration 
80 applies.
81
82 \textit{This can occur, for example, for a \addtoindex{C} 
83 or \addtoindex{C++} external variable (one that is defined 
84 and allocated in another compilation unit) and whose location 
85 varies in the current unit due to optimization.}
86
87 The location of a variable may be further specified with 
88 \addtoindexx{segment attribute!and data segment}
89 a \DWATsegment{} attribute, if appropriate.
90
91 \item A \DWATtype{} attribute describing the type of the variable,
92 constant or formal parameter.
93
94 \item If the variable entry represents the defining declaration
95 for a C++ static data member of a structure, class or union,
96 the entry has a \DWATspecification{} attribute, whose value is a
97 \livelink{chap:classreference}{reference} to the debugging information entry representing the
98 declaration of this data member. The referenced entry has the
99 tag \DWTAGmember{} and will be a child of some class, structure
100 or union type entry.
101
102 If the variable entry represents a
103 non-defining declaration, \DWATspecification{} may be used
104 to reference the defining declaration of the variable. If
105 no \DWATspecification{} attribute is present, the defining
106 declaration may be found as a global definition either in the
107 current compilation unit or in another compilation unit with
108 the \DWATexternal{} attribute.  
109
110 Variable entries containing
111 the \DWATspecification{} attribute do not need to duplicate
112 information provided by the declaration entry referenced by
113 the specification attribute. In particular, such variable
114 entries do not need to contain attributes for the name or
115 type of the data member whose definition they 
116 % Getting the link target in a good spot is tricky. So putting
117 %this one a little early.
118 \hypertarget{chap:DWATvariableparameternonconstantparameterflag}{}
119 represent.
120
121 \needlines{4}
122 \item A \DWATvariableparameterDEFN{}
123 attribute\addtoindexx{variable parameter attribute}, 
124 which is a \livelink{chap:classflag}{flag},
125 if a formal parameter entry represents a parameter whose
126 value in the calling function may be modified by the callee.
127 The absence of this attribute implies that the parameter\textquoteright s
128 value in the calling function cannot be modified by the callee.
129
130 \item A \DWATisoptionalDEFN{} attribute, 
131 \hypertarget{chap:DWATisoptionaloptionalparameter}{}
132 which 
133 \addtoindexx{is optional attribute}
134 is a \livelink{chap:classflag}{flag}, if a
135 parameter entry represents an \addtoindex{optional parameter}.
136
137 \item A \DWATdefaultvalueDEFN{} attribute 
138 \addtoindexx{default value attribute}
139 for 
140 \addtoindexx{formal parameter entry!with default value}
141 a formal parameter
142 \hypertarget{chap:DWATdefaultvaluedefaultvalueofparameter}{}
143 entry. The value of this attribute may be a constant, or a reference to the
144 debugging information entry for a variable, or a reference to a
145 debugging information entry containing a DWARF procedure.  If the
146 attribute form is of class constant, that constant is interpreted as
147 a default value of the type of the formal parameter. If the attribute
148 form is of class reference, and the referenced entry is for a
149 variable, the default value of the parameter is the value of the
150 referenced variable.  If the reference value is 0, no default value
151 has been specified.  Otherwise, the attribute represents an implicit
152 \DWOPcallref{} to the referenced debugging information entry, and
153 the default value of the parameter is the value returned by that
154 DWARF procedure, interpreted as a value of the type of the formal
155 parameter.
156
157 \textit{For a constant form there is no way to 
158 express the absence of a default value.}
159
160 \item A \DWATconstvalueDEFN{} attribute
161 \addtoindexx{constant value attribute}  
162 \hypertarget{chap:DWATconstvalueconstantobject}{}
163 for an entry describing a
164 variable or formal parameter whose value is constant and not
165 represented by an object in the address space of the program,
166 or an entry describing a named constant. (Note that such
167 an entry does not have a location attribute.) The value of
168 this attribute may be a string or any of the constant data
169 or data block forms, 
170 as appropriate for the representation
171 of the variable's value. The value is the actual constant
172 value of the variable, represented as it would be on the
173 target architecture.  
174
175 \textit{One way in which a formal parameter
176 with a constant value and no location can arise is for a
177 formal parameter of an inlined subprogram that corresponds
178 to a constant actual parameter of a call that is inlined.
179 }
180
181 \item A \DWATstartscopeDEFN{}\addtoindexx{start scope attribute}
182 \hypertarget{chap:DWATstartscopeobjectdeclaration}{}
183 attribute if the address range for the scope of an
184 object is a subset of the address range for the
185 the lexical scope most closely enclosing the object. 
186 There are two cases:
187 \begin{enumerate}[a) ]
188 \item If address range for the scope of the object entry 
189 includes all of addresses for the containing scope except 
190 for a contiguous sequence of bytes at the beginning of the 
191 address range for the containing scope, then the address is 
192 specified using a value of class constant. If the address
193 range for the containing scope is contiguous, the value of 
194 this attribute is the offset in bytes of the beginning of 
195 the address range for the scope of the object from the low 
196 PC value of the debugging information entry that defines
197 that containing scope. If the address range of the containing 
198 scope is non-contiguous 
199 (see \refersec{chap:noncontiguousaddressranges})
200 the value of this attribute is the offset in bytes of the 
201 beginning of the address range for the scope of the object 
202 from the beginning of the first \addtoindex{range list} entry
203 for the containing scope that is not a base selection entry, 
204 a default selection entry or an end-of-list entry.
205
206 \needlines{4}
207 \item Otherwise, the set of addresses for the scope of the 
208 object is specified using a value of class \CLASSrangelistptr{}. 
209 This value indicates the beginning of a \addtoindex{range list}
210 (see \ref{chap:noncontiguousaddressranges}).
211 \end{enumerate}
212
213
214 \textit{The scope of a variable may begin somewhere in the middle of
215 a lexical \livelink{chap:lexicalblock}{block} in a language 
216 that allows executable code in a
217 \nolink{block} before a variable declaration, or where one declaration
218 containing initialization code may change the scope of a
219 subsequent declaration.  For example, in the following \addtoindex{C} code:}
220
221 \begin{lstlisting}
222 float x = 99.99;
223 int myfunc()
224 {
225     float f = x;
226     float x = 88.99;
227     return 0;
228 }
229 \end{lstlisting}
230
231 \textit{\addtoindex{C} scoping rules require that the value of the variable x
232 assigned to the variable f in the initialization sequence is
233 the value of the global variable x, rather than the local x,
234 because the scope of the local variable x only starts after
235 the full declarator for the local x.}
236
237 \textit{Due to optimization, the scope of an object may be
238 non-contiguous and require use of a \addtoindex{range list} even when
239 the containing scope is contiguous. Conversely, the scope of
240 an object may not require its own \addtoindex{range list} even when the
241 containing scope is non\dash contiguous.}
242
243 \item A \DWATendianityDEFN{} attribute,
244 \addtoindexx{endianity attribute}
245 \hypertarget{chap:DWATendianityendianityofdata}{}
246 whose value is a constant that 
247 \addtoindexx{big-endian encoding|see{endianity attribute}}
248 specifies the endianity of the object. The value of
249 this attribute specifies an ABI-defined 
250 \byteorder{ing} \addtoindexx{ordering attribute} for
251 the value of the object. If omitted, the default endianity
252 of data for the given type is assumed.  
253
254 The set of values
255 and their meaning for this attribute is given in 
256 Table \ref{tab:endianityattributevalues}.
257
258 \begin{table}[h]
259 \caption{Endianity attribute values}
260 \label{tab:endianityattributevalues}
261 \centering
262 \begin{tabular}{l|P{9cm}}
263 \hline
264 Name&Meaning\\ \hline
265 \DWENDdefaultTARG{} &  Default endian encoding
266   (equivalent to the \mbox{absence} of a 
267   \DWATendianity{} attribute) \\
268 \DWENDbigTARG{} & Big\dash endian encoding \\
269 \DWENDlittleTARG& Little-endian encoding \\
270 \hline
271 \end{tabular}
272 \end{table}
273
274
275 These represent the default encoding formats as defined by
276 the target architecture's ABI or processor definition. The
277 exact definition of these formats may differ in subtle ways
278 for different architectures.
279
280 \needlines{6}
281 \item A \DWATconstexprDEFN{} attribute,
282 \addtoindex{constant expression attribute}
283 \hypertarget{chap:DWATconstexprcompiletimeconstantobject}{}
284 which is a \CLASSflag, if a
285 variable entry represents a \addtoindex{C++} object declared with the
286 \texttt{constexpr} specifier. This attribute indicates that the
287 variable can be evaluated as a compile\dash time constant.  
288
289 \textit{In \addtoindex{C++},
290 a variable declared with \texttt{constexpr} is implicitly 
291 \texttt{const}. Such a variable has a \DWATtype{} attribute 
292 whose value is a \CLASSreference{} to a debugging information 
293 entry describing a \texttt{const} qualified type.}
294
295 \item A \DWATlinkagename{} attribute for a 
296 variable or constant entry as described in 
297 Section \refersec{chap:linkagenames}.
298
299 \end{enumerate}
300
301 \section{Common Block Entries}
302 \label{chap:commonblockentries}
303 A Fortran 
304 \livetargi{chap:fortrancommonblock}{common}{Fortran!common block}
305 \livetargi{chap:commonblockentry}{block}{common block entry} 
306 may 
307 \addtoindexx{Fortran!common block}
308 be described by a debugging information entry with the 
309 tag \DWTAGcommonblockTARG. 
310
311 The common \nolink{block} 
312 entry has a \DWATname{} attribute 
313 \addtoindexx{name attribute}
314 whose value is a null-terminated
315 string containing the
316 \livetargi{chap:commonblockreferenceattribute}{common block}{common block reference attribute} 
317 name as it appears in the source program. It may also have a
318 \DWATlinkagename{} attribute as described in 
319 Section \refersec{chap:linkagenames}. 
320
321 A common block entry also has a \DWATlocation{} attribute
322 \addtoindexx{location attribute}
323 whose value describes the
324 location of the beginning of the common \nolink{block}. 
325
326 The common
327 \nolink{block} entry owns debugging information entries describing
328 the variables contained within the common \nolink{block}.
329
330 \textit{\addtoindex{Fortran} allows each declarer of a common block 
331 to independently define its contents; thus, common blocks are not types.}
332
333 \needlines{8}
334 \section{Namelist Entries}
335 \label{chap:namelistentries}
336 \textit{At least one language, Fortran 90, has the concept of a
337 namelist. A namelist is an ordered list of the names of some
338 set of declared objects. The namelist object itself may be used
339 as a replacement for the list of names in various contexts.}
340
341 A namelist is represented by a debugging information entry
342 with the 
343 tag \DWTAGnamelistTARG. 
344 \addtoindexx{namelist entry}
345 If the namelist itself has a
346 name, the namelist entry has a \DWATname{} attribute,
347 \addtoindexx{name attribute}
348 whose value is a null-terminated
349 string containing the namelist\textquoteright{}s
350 name as it appears in the source program.
351
352 Each 
353 \hypertarget{chap:DWATnamelistitemnamelistitem}{}
354 name that is part of the namelist is represented
355 by a debugging information entry with the tag
356 \DWTAGnamelistitemTARG. 
357 Each such entry is a child of the
358 namelist entry, and all of the 
359 namelist item entries for a
360 \addtoindexx{namelist item entry}
361 given namelist are ordered as were the list of names they
362 correspond to in the source program.
363
364 Each namelist item entry contains a 
365 \DWATnamelistitemDEFN{} attribute
366 \addtoindexx{namelist item attribute}
367 whose 
368 \addtoindexx{namelist item entry}
369 value is a \livelink{chap:classreference}{reference} to the debugging
370 information entry representing the declaration of the item
371 whose name appears in the namelist.
372
373