c4005b788e7bde291667eb9142a71ddf2454801a
[dwarf-doc.git] / dwarf5 / latexdoc / generaldescription.tex
1 \chapter{General Description}
2 \label{chap:generaldescription}
3 \section{The Debugging Information Entry (DIE)}
4 \label{chap:thedebuggingentrydie}
5 DWARF 
6 \addtoindexx{debugging information entry}
7 uses 
8 \addtoindexx{DIE|see{debugging information entry}}
9 a series of debugging information entries (DIEs) to 
10 define a low-level
11 representation of a source program. 
12 Each debugging information entry consists of an identifying
13 \addtoindex{tag} and a series of 
14 \addtoindex{attributes}. 
15 An entry, or group of entries together, provide a description of a
16 corresponding 
17 \addtoindex{entity} in the source program. 
18 The tag specifies the class to which an entry belongs
19 and the attributes define the specific characteristics of the entry.
20
21 The set of tag names 
22 \addtoindexx{tag names|see{debugging information entry}}
23 is listed in Table \refersec{tab:tagnames}. 
24 The debugging information entries they identify are
25 described in Chapters 3, 4 and 5.
26
27 % These each need to link to definition page: FIXME
28
29
30 \begin{table}[p]
31 \caption{Tag names}
32 \label{tab:tagnames}
33 \simplerule[6in]
34 \autocols[0pt]{c}{2}{l}{
35 \DWTAGaccessdeclaration,
36 \DWTAGarraytype,
37 \DWTAGbasetype,
38 \DWTAGcatchblock,
39 \DWTAGclasstype,
40 \DWTAGcoarraytype,
41 \DWTAGcommonblock,
42 \DWTAGcommoninclusion,
43 \DWTAGcompileunit,
44 \DWTAGcondition,
45 \DWTAGconsttype,
46 \DWTAGconstant,
47 \DWTAGdwarfprocedure,
48 \DWTAGentrypoint,
49 \DWTAGenumerationtype,
50 \DWTAGenumerator,
51 \DWTAGfiletype,
52 \DWTAGformalparameter,
53 \DWTAGfriend,
54 \DWTAGgenericsubrange,
55 \DWTAGimporteddeclaration,
56 \DWTAGimportedmodule,
57 \DWTAGimportedunit,
58 \DWTAGinheritance,
59 \DWTAGinlinedsubroutine,
60 \DWTAGinterfacetype,
61 \DWTAGlabel,
62 \DWTAGlexicalblock,
63 \DWTAGmodule,
64 \DWTAGmember,
65 \DWTAGnamelist,
66 \DWTAGnamelistitem,
67 \DWTAGnamespace,
68 \DWTAGpackedtype,
69 \DWTAGpartialunit,
70 \DWTAGpointertype,
71 \DWTAGptrtomembertype,
72 \DWTAGreferencetype,
73 \DWTAGrestricttype,
74 \DWTAGrvaluereferencetype,
75 \DWTAGsettype,
76 \DWTAGsharedtype,
77 \DWTAGstringtype,
78 \DWTAGstructuretype,
79 \DWTAGsubprogram,
80 \DWTAGsubrangetype,
81 \DWTAGsubroutinetype,
82 \DWTAGtemplatealias,
83 \DWTAGtemplatetypeparameter,
84 \DWTAGtemplatevalueparameter,
85 \DWTAGthrowntype,
86 \DWTAGtryblock,
87 \DWTAGtypedef,
88 \DWTAGtypeunit,
89 \DWTAGuniontype,
90 \DWTAGunspecifiedparameters,
91 \DWTAGunspecifiedtype,
92 \DWTAGvariable,
93 \DWTAGvariant,
94 \DWTAGvariantpart,
95 \DWTAGvolatiletype,
96 \DWTAGwithstmt
97 }
98 \simplerule[6in]
99 \end{table}
100
101
102 \textit{The debugging information entry descriptions 
103 in Sections 3, 4 and 5 generally include mention of
104 most, but not necessarily all, of the attributes 
105 that are normally or possibly used with the entry.
106 Some attributes, whose applicability tends to be 
107 pervasive and invariant across many kinds of
108 debugging information entries, are described in 
109 this section and not necessarily mentioned in all
110 contexts where they may be appropriate. 
111 Examples include 
112 \DWATartificial, 
113 the \livelink{chap:declarationcoordinates}{declaration coordinates}, and 
114 \DWATdescription, 
115 among others.}
116
117 The debugging information entries are contained 
118 in the \dotdebuginfo{} and 
119 \dotdebugtypes{}
120 sections of an object file.
121
122
123 \section{Attribute Types}
124 \label{chap:attributetypes}
125 Each attribute value is characterized by an attribute name. 
126 \addtoindexx{attribute duplication}
127 No more than one attribute with a given name may appear in any
128 debugging information entry. 
129 There are no limitations on the
130 \addtoindexx{attribute ordering}
131 ordering of attributes within a debugging information entry.
132
133 The attributes are listed in Table \refersec{tab:attributenames}.  
134
135 The permissible values
136 \addtoindexx{attribute value classes}
137 for an attribute belong to one or more classes of attribute
138 value forms.  
139 Each form class may be represented in one or more ways. 
140 For example, some attribute values consist
141 of a single piece of constant data. 
142 \doublequote{Constant data}
143 is the class of attribute value that those attributes may have. 
144 There are several representations of constant data,
145 however (one, two, ,four, or eight bytes, and variable length
146 data). 
147 The particular representation for any given instance
148 of an attribute is encoded along with the attribute name as
149 part of the information that guides the interpretation of a
150 debugging information entry.  
151
152 Attribute value forms belong
153 \addtoindexx{tag names!list of}
154 to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
155
156 \setlength{\extrarowheight}{0.1cm}
157 \addtoindexx{attributes!list of}
158 \begin{longtable}{l|p{9cm}}
159   \caption{Attribute names} \label{tab:attributenames} \\
160   \hline \bfseries Attribute&\bfseries Identifies or Specifies \\ \hline
161 \endfirsthead
162   \bfseries Attribute&\bfseries Identifies or Specifies \\ \hline
163 \endhead
164   \hline \emph{Continued on next page}
165 \endfoot
166   \hline
167 \endlastfoot
168 \DWATabstractoriginTARG
169 &\livelinki{chap:DWATabstractorigininlineinstance}{Inline instances of inline subprograms} {inline instances of inline subprograms} \\
170 % Heren livelink we cannot use \dash or \dash{}.
171 &\livelinki{chap:DWATabstractoriginoutoflineinstance}{Out-of-line instances of inline subprograms}{out-of-line instances of inline subprograms} \\
172 \DWATaccessibilityTARG
173 &\livelink{chap:DWATaccessibilitycandadadeclarations}{C++ and Ada declarations} \addtoindexx{Ada} \\
174 &\livelink{chap:DWATaccessibilitycppbaseclasses}{C++ base classes} \\
175 &\livelink{chap:DWATaccessibilitycppinheritedmembers}{C++ inherited members} \\
176 \DWATaddressclassTARG
177 &\livelinki{chap:DWATadressclasspointerorreferencetypes}{Pointer or reference types}{pointer or reference types}  \\
178 &\livelinki{chap:DWATaddressclasssubroutineorsubroutinetype}{Subroutine or subroutine type}{subroutine or subroutine type} \\
179 \DWATallocatedTARG
180 &\livelinki{chap:DWATallocatedallocationstatusoftypes}{Allocation status of types}{allocation status of types}  \\
181 \DWATartificialTARG
182 &\livelinki{chap:DWATartificialobjectsortypesthat}{Objects or types that are not
183 actually declared in the source}{objects or types that are not actually declared in the source}  \\
184 \DWATassociatedTARG{} 
185 &\livelinki{chap:DWATassociatedassociationstatusoftypes}{Association status of types}{association status of types} \\
186 \DWATbasetypesTARG{} 
187 &\livelinki{chap:DWATbasetypesprimitivedatatypesofcompilationunit}{Primitive data types of compilation unit}{primitive data types of compilation unit} \\
188 \DWATbinaryscaleTARG{} 
189 &\livelinki{chap:DWATbinaryscalebinaryscalefactorforfixedpointtype}{Binary scale factor for fixed-point type}{binary scale factor for fixed-point type} \\
190 \DWATbitoffsetTARG{} 
191 &\livelinki{chap:DWATbitoffsetbasetypebitlocation}{Base type bit location}{base type bit location} \\
192 &\livelinki{chap:DWATbitoffsetdatamemberbitlocation}{Data member bit location}{data member bit location} \\
193 \DWATbitsizeTARG{} 
194 &\livelinki{chap:DWATbitsizebasetypebitsize}{Base type bit size}{base type bit size} \\
195 &\livelinki{chap:DWATbitsizedatamemberbitsize}{Data member bit size}{data member bit size} \\
196 \newpage
197 \DWATbitstrideTARG{} 
198 &\livelinki{chap:DWATbitstridearrayelementstrideofarraytype}{Array element stride (of array type)}{array element stride (of array type)} \\
199 &\livelinki{chap:DWATbitstridesubrangestridedimensionofarraytype}{Subrange stride (dimension of array type)}{subrange stride (dimension of array type)} \\
200 &\livelinki{chap:DWATbitstrideenumerationstridedimensionofarraytype}{Enumeration stride (dimension of array type)}{enumeration stride (dimension of array type)} \\
201 \DWATbytesizeTARG{} 
202 &\livelinki{chap:DWATbytesizedataobjectordatatypesize}{Data object or data type size}{data object or data type size} \\
203 \DWATbytestrideTARG{} 
204 &\livelinki{chap:DWATbytestridearrayelementstrideofarraytype}{Array element stride (of array type)}{array element stride (of array type)} \\
205 &\livelinki{chap:DWATbytestridesubrangestridedimensionofarraytype}{Subrange stride (dimension of array type)}{subrange stride (dimension of array type)} \\
206 &\livelinki{chap:DWATbytestrideenumerationstridedimensionofarraytype}{Enumeration stride (dimension of array type)}{enumeration stride (dimension of array type)} \\
207 \DWATcallcolumnTARG{} 
208 &\livelinki{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}{Column position of inlined subroutine call}{column position of inlined subroutine call}\\
209 \DWATcallfileTARG
210 &\livelinki{chap:DWATcallfilefilecontaininginlinedsubroutinecall}{File containing inlined subroutine call}{file containing inlined subroutine call} \\
211 \DWATcalllineTARG{} 
212 &\livelinki{chap:DWATcalllinelinenumberofinlinedsubroutinecall}{Line number of inlined subroutine call}{line number of inlined subroutine call} \\
213 \DWATcallingconventionTARG{} 
214 &\livelinki{chap:DWATcallingconventionsubprogramcallingconvention}{Subprogram calling convention}{subprogram calling convention} \\
215 \DWATcommonreferenceTARG
216 &\livelinki{chap:commonreferencecommonblockusage}{Common block usage}{common block usage} \\
217 \DWATcompdirTARG
218 &\livelinki{chap:DWATcompdircompilationdirectory}{Compilation directory}{compilation directory} \\
219 \DWATconstvalueTARG
220 &\livelinki{chap:DWATconstvalueconstantobject}{Constant object}{constant object} \\
221 &\livelinki{chap:DWATconstvalueenumerationliteralvalue}{Enumeration literal value}{enumeration literal value} \\
222 &\livelinki{chap:DWATconstvaluetemplatevalueparameter}{Template value parameter}{template value parameter} \\
223 \DWATconstexprTARG
224 &\livelinki{chap:DWATconstexprcompiletimeconstantobject}{Compile-time constant object}{compile-time constant object} \\
225 &\livelinki{chap:DWATconstexprcompiletimeconstantfunction}{Compile-time constant function}{compile-time constant function} \\
226 \DWATcontainingtypeTARG
227 &\livelinki{chap:DWATcontainingtypecontainingtypeofpointertomembertype}{Containing type of pointer to member type}{containing type of pointer to member type} \\
228 \DWATcountTARG
229 &\livelinki{chap:DWATcountelementsofsubrangetype}{Elements of subrange type}{elements ofbreg subrange type} \\
230 \DWATdatabitoffsetTARG
231 &\livelinki{chap:DWATdatabitoffsetbasetypebitlocation}{Base type bit location}{base type bit location} \\
232 &\livelinki{chap:DWATdatabitoffsetdatamemberbitlocation}{Data member bit location}{data member bit location} \\
233 \DWATdatalocationTARG{} 
234 &\livelinki{chap:DWATdatalocationindirectiontoactualdata}{Indirection to actual data}{indirection to actual data} \\
235 \DWATdatamemberlocationTARG
236 &\livelinki{chap:DWATdatamemberlocationdatamemberlocation}{Data member location}{data member location} \\
237 &\livelinki{chap:DWATdatamemberlocationinheritedmemberlocation}{Inherited member location}{inherited member location} \\
238 \DWATdecimalscaleTARG
239 &\livelinki{chap:DWATdecimalscaledecimalscalefactor}{Decimal scale factor}{decimal scale factor} \\
240 \DWATdecimalsignTARG
241 &\livelinki{chap:DWATdecimalsigndecimalsignrepresentation}{Decimal sign representation}{decimal sign representation} \\
242 \DWATdeclcolumnTARG
243 &\livelinki{chap:DWATdeclcolumncolumnpositionofsourcedeclaration}{Column position of source declaration}{column position of source declaration} \\
244 \DWATdeclfileTARG
245 &\livelinki{chap:DWATdeclfilefilecontainingsourcedeclaration}{File containing source declaration}{file containing source declaration} \\
246 \DWATdecllineTARG
247 &\livelinki{chap:DWATdecllinelinenumberofsourcedeclaration}{Line number of source declaration}{line number of source declaration} \\
248 \DWATdeclarationTARG
249 &\livelinki{chap:DWATdeclarationincompletenondefiningorseparateentitydeclaration}{Incomplete, non-defining, or separate entity declaration}{incomplete, non-defining, or separate entity declaration} \\
250 \DWATdefaultvalueTARG
251 &\livelinki{chap:DWATdefaultvaluedefaultvalueofparameter}{Default value of parameter}{default value of parameter} \\
252 \DWATdescriptionTARG{} 
253 &\livelinki{chap:DWATdescriptionartificialnameordescription}{Artificial name or description}{artificial name or description} \\
254 \DWATdigitcountTARG
255 &\livelinki{chap:DWATdigitcountdigitcountforpackeddecimalornumericstringtype}{Digit count for packed decimal or numeric string type}{digit count for packed decimal or numeric string type} \\
256 \DWATdiscrTARG
257 &\livelinki{chap:DWATdiscrdiscriminantofvariantpart}{Discriminant of variant part}{discriminant of variant part} \\
258 \DWATdiscrlistTARG
259 &\livelinki{chap:DWATdiscrlistlistofdiscriminantvalues}{List of discriminant values}{list of discriminant values} \\
260 \DWATdiscrvalueTARG
261 &\livelinki{chap:DWATdiscrvaluediscriminantvalue}{Discriminant value}{discriminant value} \\
262 \DWATelementalTARG
263 &\livelinki{chap:DWATelementalelementalpropertyofasubroutine}{Elemental property of a subroutine}{elemental property of a subroutine} \\
264 \DWATencodingTARG
265 &\livelinki{chap:DWATencodingencodingofbasetype}{Encoding of base type}{encoding of base type} \\
266 \DWATendianityTARG
267 &\livelinki{chap:DWATendianityendianityofdata}{Endianity of data}{endianity of data} \\
268 \DWATentrypcTARG
269 &\livelinki{chap:DWATentrypcentryaddressofmoduleinitialization}{Entry address of module initialization}{entry address of module initialization}\\
270 &\livelinki{chap:DWATentrypcentryaddressofsubprogram}{Entry address of subprogram}{entry address of subprogram} \\
271 &\livelinki{chap:DWATentrypcentryaddressofinlinedsubprogram}{Entry address of inlined subprogram}{entry address of inlined subprogram}\\
272 \DWATenumclassTARG
273 &\livelinki{chap:DWATenumclasstypesafeenumerationdefinition}{Type safe enumeration definition}{type safe enumeration definition}\\
274 \DWATexplicitTARG
275 &\livelinki{chap:DWATexplicitexplicitpropertyofmemberfunction}{Explicit property of member function}{explicit property of member function}\\
276 \DWATextensionTARG
277 &\livelinki{chap:DWATextensionpreviousnamespaceextensionororiginalnamespace}{Previous namespace extension or original namespace}{previous namespace extension or original namespace}\\
278 \DWATexternalTARG
279 &\livelinki{chap:DWATexternalexternalsubroutine}{External subroutine}{external subroutine} \\
280 &\livelinki{chap:DWATexternalexternalvariable}{External variable}{external variable} \\
281 \DWATframebaseTARG
282 &\livelinki{chap:DWATframebasesubroutineframebaseaddress}{Subroutine frame base address}{subroutine frame base address} \\
283 \DWATfriendTARG
284 &\livelinki{chap:DWATfriendfriendrelationship}{Friend relationship}{friend relationship} \\
285 \DWAThighpcTARG
286 &\livelinki{chap:DWAThighpccontiguousrangeofcodeaddresses}{Contiguous range of code addresses}{contiguous range of code addresses} \\
287 \DWATidentifiercaseTARG
288 &\livelinki{chap:DWATidentifiercaseidentifiercaserule}{Identifier case rule}{identifier case rule} \\
289 \DWATimportTARG
290 &\livelinki{chap:DWATimportimporteddeclaration}{Imported declaration}{imported declaration} \\
291 &\livelinki{chap:DWATimportimportedunit}{Imported unit}{imported unit} \\
292 &\livelinki{chap:DWATimportnamespacealias}{Namespace alias}{namespace alias} \\
293 &\livelinki{chap:DWATimportnamespaceusingdeclaration}{Namespace using declaration}{namespace using declaration} \\
294 &\livelinki{chap:DWATimportnamespaceusingdirective}{Namespace using directive}{namespace using directive} \\
295 \DWATinlineTARG
296 &\livelinki{chap:DWATinlineabstracttinstance}{Abstract instance}{abstract instance} \\
297 &\livelinki{chap:DWATinlineinlinedsubroutine}{Inlined subroutine}{inlined subroutine} \\
298 \DWATisoptionalTARG
299 &\livelinki{chap:DWATisoptionaloptionalparameter}{Optional parameter}{optional parameter} \\
300 \DWATlanguageTARG
301 &\livelinki{chap:DWATlanguageprogramminglanguage}{Programming language}{programming language} \\
302 \DWATlinkagenameTARG
303 &\livelinki{chap:DWATlinkagenameobjectfilelinkagenameofanentity}{Object file linkage name of an entity}{object file linkage name of an entity}\\
304 \DWATlocationTARG
305 &\livelinki{chap:DWATlocationdataobjectlocation}{Data object location}{data object location}\\
306 \DWATlowpcTARG
307 &\livelinki{chap:DWATlowpccodeaddressorrangeofaddresses}{Code address or range of addresses}{code address or range of addresses}\\
308 \DWATlowerboundTARG
309 &\livelinki{chap:DWATlowerboundlowerboundofsubrange}{Lower bound of subrange}{lower bound of subrange} \\
310 \DWATmacroinfoTARG
311 &\livelinki{chap:DWATmacroinfomacroinformation}{Macro information} {macro information} (\texttt{\#define}, \texttt{\#undef})\\
312 \DWATmainsubprogramTARG
313 &\livelinki{chap:DWATmainsubprogrammainorstartingsubprogram}{Main or starting subprogram}{main or starting subprogram} \\
314 &\livelinki{chap:DWATmainsubprogramunitcontainingmainorstartingsubprogram}{Unit containing main or starting subprogram}{unit containing main or starting subprogram}\\
315 \DWATmutableTARG
316 &\livelinki{chap:DWATmutablemutablepropertyofmemberdata}{Mutable property of member data}{mutable property of member data} \\
317 \DWATnameTARG
318 &\livelinki{chap:DWATnamenameofdeclaration}{Name of declaration}{name of declaration}\\
319 &\livelinki{chap:DWATnamepathnameofcompilationsource}{Path name of compilation source}{path name of compilation source} \\
320 \DWATnamelistitemTARG
321 &\livelinki{chap:DWATnamelistitemnamelistitem}{Namelist item}{namelist item}\\
322 \DWATobjectpointerTARG
323 &\livelinki{chap:DWATobjectpointerobjectthisselfpointerofmemberfunction}{Object (\texttt{this}, \texttt{self}) pointer of member function}{object (\texttt{this}, \texttt{self}) pointer of member function}\\
324 \DWATorderingTARG
325 &\livelinki{chap:DWATorderingarrayrowcolumnordering}{Array row/column ordering} {array row/column ordering}\\
326 \DWATpicturestringTARG
327 &\livelinki{chap:DWATpicturestringpicturestringfornumericstringtype}{Picture string for numeric string type}{picture string for numeric string type} \\
328 \DWATpriorityTARG
329 &\livelinki{chap:DWATprioritymodulepriority}{Module priority}{module priority}\\
330 \DWATproducerTARG
331 &\livelinki{chap:DWATproducercompileridentification}{Compiler identification}{compiler identification}\\
332 \DWATprototypedTARG
333 &\livelinki{chap:DWATprototypedsubroutineprototype}{Subroutine prototype}{subroutine prototype}\\
334 \DWATpureTARG
335 &\livelinki{chap:DWATpurepurepropertyofasubroutine}{Pure property of a subroutine}{pure property of a subroutine} \\
336 \DWATrangesTARG
337 &\livelinki{chap:DWATrangesnoncontiguousrangeofcodeaddresses}{Non-contiguous range of code addresses}{non-contiguous range of code addresses} \\
338 \DWATrankTARG
339 &\livelinki{chap:DWATrankofdynamicarray}{Dynamic number of array dimensions}{dynamic number of array dimensions} \\
340 \DWATrecursiveTARG
341 &\livelinki{chap:DWATrecursiverecursivepropertyofasubroutine}{Recursive property of a subroutine}{recursive property of a subroutine} \\
342 \DWATreturnaddrTARG
343 &\livelinki{chap:DWATreturnaddrsubroutinereturnaddresssavelocation}{Subroutine return address save location}{subroutine return address save location} \\
344 \DWATsegmentTARG
345 &\livelinki{chap:DWATsegmentaddressinginformation}{Addressing information}{addressing information} \\
346 \DWATsiblingTARG
347 &\livelinki{chap:DWATsiblingdebugginginformationentryrelationship}{Debugging information entry relationship}{debugging information entry relationship} \\
348 \DWATsmallTARG
349 &\livelinki{chap:DWATsmallscalefactorforfixedpointtype}{Scale factor for fixed-point type}{scale factor for fixed-point type} \\
350 \DWATsignatureTARG
351 &\livelinki{chap:DWATsignaturetypesignature}{Type signature}{type signature}\\
352 \DWATspecificationTARG
353 &\livelinki{chap:DWATspecificationincompletenondefiningorseparatedeclaration}{Incomplete, non-defining, or separate declaration corresponding to a declaration}{incomplete, non-defining, or separate declaration corresponding to a declaration} \\
354 \DWATstartscopeTARG
355 &\livelinki{chap:DWATstartscopeobjectdeclaration}{Object declaration}{object declaration}\\
356 &\livelinki{chap:DWATstartscopetypedeclaration}{Type declaration}{type declaration}\\
357 \DWATstaticlinkTARG
358 &\livelinki{chap:DWATstaticlinklocationofuplevelframe}{Location of uplevel frame}{location of uplevel frame} \\
359 \DWATstmtlistTARG
360 &\livelinki{chap:DWATstmtlistlinenumberinformationforunit}{Line number information for unit}{line number information for unit}\\
361 \DWATstringlengthTARG
362 &\livelinki{chap:DWATstringlengthstringlengthofstringtype}{String length of string type}{string length of string type}
363  \\
364 \DWATstringlengthbitsizeTARG
365 &\livelinki{chap:DWATstringlengthstringlengthofstringtype}{Size of string length of string type}{string length of string type!size of}
366  \\
367 \DWATstringlengthbytesizeTARG
368 &\livelinki{chap:DWATstringlengthstringlengthofstringtype}{Size of string length of string type}{string length of string type!size of}
369  \\
370 \DWATthreadsscaledTARG
371 &\livelink{chap:DWATthreadsscaledupcarrayboundthreadsscalfactor}{UPC!array bound THREADS scale factor}\\
372 \DWATtrampolineTARG
373 &\livelinki{chap:DWATtrampolinetargetsubroutine}{Target subroutine}{target subroutine of trampoline} \\
374 \DWATtypeTARG
375 &\livelinki{chap:DWATtypetypeofdeclaration}{Type of declaration}{type of declaration} \\
376 &\livelinki{chap:DWATtypetypeofsubroutinereturn}{Type of subroutine return}{type of subroutine return} \\
377 \DWATupperboundTARG
378 &\livelinki{chap:DWATupperboundupperboundofsubrange}{Upper bound of subrange}{upper bound of subrange} \\
379 \DWATuselocationTARG
380 &\livelinki{chap:DWATuselocationmemberlocationforpointertomembertype}{Member location for pointer to member type}{member location for pointer to member type} \\
381 \DWATuseUTFeightTARG\addtoindexx{use UTF8 attribute}\addtoindexx{UTF-8}
382 &\livelinki{chap:DWATuseUTF8compilationunitusesutf8strings}{Compilation unit uses UTF-8 strings}{compilation unit uses UTF-8 strings} \\
383 \DWATvariableparameterTARG
384 &\livelinki{chap:DWATvariableparameternonconstantparameterflag}{Non-constant parameter flag}{non-constant parameter flag}  \\
385 \DWATvirtualityTARG
386 &\livelinki{chap:DWATvirtualityvirtualityindication}{Virtuality indication}{virtuality indication} \\
387 &\livelinki{chap:DWATvirtualityvirtualityofbaseclass}{Virtuality of base class} {virtuality of base class} \\
388 &\livelinki{chap:DWATvirtualityvirtualityoffunction}{Virtuality of function}{virtuality of function} \\
389 \DWATvisibilityTARG
390 &\livelinki{chap:DWATvisibilityvisibilityofdeclaration}{Visibility of declaration}{visibility of declaration} \\
391 \DWATvtableelemlocationTARG
392 &\livelinki{chap:DWATvtableelemlocationvirtualfunctiontablevtableslot}{Virtual function vtable slot}{virtual function vtable slot}\\
393 \end{longtable}
394
395 \addtoindexx{address|see {\textit{also} address class}}
396 \addtoindexx{block|see {\textit{also} block class}}
397 \addtoindexx{constant|see {\textit{also} constant class}}
398 \addtoindexx{exprloc|see {\textit{also} exprloc class}}
399 \addtoindexx{flag|see {\textit{also} flag class}}
400 \addtoindexx{lineptr|see {\textit{also} lineptr class}}
401 \addtoindexx{loclistptr|see {\textit{also} loclistptr class}}
402 \addtoindexx{macptr|see {\textit{also} macptr class}}
403 \addtoindexx{rangelistptr|see {\textit{also} rangelistptr class}}
404 \addtoindexx{reference|see {\textit{also} reference class}}
405 \addtoindexx{string|see {\textit{also} string class}}
406 \addtoindexx{class of attribute value!address|see {address class}}
407 \addtoindexx{class of attribute value!block|see {block class}}
408 \addtoindexx{class of attribute value!constant|see {constant class}}
409 \addtoindexx{class of attribute value!exprloc|see {exprloc class}}
410 \addtoindexx{class of attribute value!flag|see {flag class}}
411 \addtoindexx{class of attribute value!lineptr|see {lineptr class}}
412 \addtoindexx{class of attribute value!loclistptr|see {loclistptr class}}
413 \addtoindexx{class of attribute value!macptr|see {macptr class}}
414 \addtoindexx{class of attribute value!rangelistptr|see {rangelistptr class}}
415 \addtoindexx{class of attribute value!reference|see {reference class}}
416 \addtoindexx{class of attribute value!string|see {string class}}
417
418 \begin{table}[here]
419 \caption{Classes of attribute value}
420 \label{tab:classesofattributevalue}
421 \centering
422 \setlength{\extrarowheight}{0.1cm}
423
424 \begin{tabular}{l|p{11cm}} \hline
425 Attribute Class & General Use and Encoding \\ \hline
426 \hypertarget{chap:classaddress}{}
427 \livelinki{datarep:classaddress}{address}{address class}
428 &Refers to some location in the address space of the described program.
429 \\
430
431 \hypertarget{chap:classblock}{}
432 \livelinki{datarep:classblock}{block}{block class}
433 & An arbitrary number of uninterpreted bytes of data.
434 \\
435  
436 \hypertarget{chap:classconstant}{}
437 \livelinki{datarep:classconstant}{constant}{constant class}
438 &One, two, four or eight bytes of uninterpreted data, or data
439 encoded in the variable length format known as LEB128 
440 (see Section \refersec{datarep:variablelengthdata}).
441
442 \textit{Most constant values are integers of one kind or
443 another (codes, offsets, counts, and so on); these are
444 sometimes called \doublequote{integer constants} for emphasis.}
445 \addtoindexx{integer constant}
446 \addtoindexx{constant class!integer}
447 \\
448
449 \hypertarget{chap:classexprloc}{}
450 \livelinki{datarep:classexprloc}{exprloc}{exprloc class}
451 &A DWARF expression or location description.
452 \\
453
454 \hypertarget{chap:classflag}{}
455 \livelinki{datarep:classflag}{flag}{flag class}
456 &A small constant that indicates the presence or absence of an attribute.
457 \\
458
459 \hypertarget{chap:classlineptr}{}
460 \livelinki{datarep:classlineptr}{lineptr}{lineptr class}
461 &Refers to a location in the DWARF section that holds line number information.
462 \\
463
464 \hypertarget{chap:classloclistptr}{}
465 \livelinki{datarep:classloclistptr}{loclistptr}{loclistptr class}
466 &Refers to a location in the DWARF section that holds location lists, which
467 describe objects whose location can change during their lifetime.
468 \\
469
470 \hypertarget{chap:classmacptr}{}
471 \livelinki{datarep:classmacptr}{macptr}{macptr class}
472 & Refers to a location in the DWARF section that holds macro definition
473  information.
474 \\
475
476 \hypertarget{chap:classrangelistptr}{}
477 \livelinki{datarep:classrangelistptr}{rangelistptr}{rangelistptr class}
478 & Refers to a location in the DWARF section that holds non\dash contiguous address ranges.
479 \\
480
481 \hypertarget{chap:classreference}{}
482 \livelinki{datarep:classreference}{reference}{reference class}
483 & Refers to one of the debugging information
484 entries that describe the program.  There are three types of
485 reference. The first is an offset relative to the beginning
486 of the compilation unit in which the reference occurs and must
487 refer to an entry within that same compilation unit. The second
488 type of reference is the offset of a debugging information
489 entry in any compilation unit, including one different from
490 the unit containing the reference. The third type of reference
491 is an indirect reference to a 
492 \addtoindexx{type signature}
493 type definition using a 64\dash bit signature 
494 for that type.
495 \\
496
497 \hypertarget{chap:classstring}{}
498 \livelinki{datarep:classstring}{string}{string class}
499 & A null\dash terminated sequence of zero or more
500 (non\dash null) bytes. Data in this class are generally
501 printable strings. Strings may be represented directly in
502 the debugging information entry or as an offset in a separate
503 string table.
504 \\
505 \hline
506 \end{tabular}
507 \end{table}
508
509 % It is difficult to get the above table to appear before
510 % the end of the chapter without a clearpage here.
511 \clearpage
512 \section{Relationship of Debugging Information Entries}
513 \label{chap:relationshipofdebugginginformationentries}
514 \textit{%
515 A variety of needs can be met by permitting a single
516 \addtoindexx{debugging information entry!ownership relation}
517 debugging information entry to \doublequote{own} an arbitrary number
518 of other debugging entries and by permitting the same debugging
519 information entry to be one of many owned by another debugging
520 information entry. 
521 This makes it possible, for example, to
522 describe the static \livelink{chap:lexicalblock}{block} structure 
523 within a source file,
524 to show the members of a structure, union, or class, and to
525 associate declarations with source files or source files
526 with shared objects.  
527 }
528
529
530 The ownership relation 
531 \addtoindexx{debugging information entry!ownership relation}
532 of debugging
533 information entries is achieved naturally because the debugging
534 information is represented as a tree. 
535 The nodes of the tree
536 are the debugging information entries themselves. 
537 The child
538 entries of any node are exactly those debugging information
539 entries owned by that node.  
540
541 \textit{%
542 While the ownership relation
543 of the debugging information entries is represented as a
544 tree, other relations among the entries exist, for example,
545 a reference from an entry representing a variable to another
546 entry representing the type of that variable. 
547 If all such
548 relations are taken into account, the debugging entries
549 form a graph, not a tree.  
550 }
551
552 The tree itself is represented
553 by flattening it in prefix order. 
554 Each debugging information
555 entry is defined either to have child entries or not to have
556 child entries (see Section \refersec{datarep:abbreviationstables}). 
557 If an entry is defined not
558 to have children, the next physically succeeding entry is a
559 sibling. 
560 If an entry is defined to have children, the next
561 physically succeeding entry is its first child. 
562 Additional
563 children are represented as siblings of the first child. 
564 A chain of sibling entries is terminated by a null entry.
565
566 In cases where a producer of debugging information feels that
567 \hypertarget{chap:DWATsiblingdebugginginformationentryrelationship}
568 it will be important for consumers of that information to
569 quickly scan chains of sibling entries, while ignoring the
570 children of individual siblings, that producer may attach 
571 \addtoindexx{sibling attribute}
572 a
573 \DWATsibling{} attribute 
574 to any debugging information entry. 
575 The
576 value of this attribute is a reference to the sibling entry
577 of the entry to which the attribute is attached.
578
579
580 \section{Target Addresses}
581 \label{chap:targetaddresses}
582 Many places in this document 
583 refer
584 \addtoindexx{address size|see{size of an address}}
585 to the size 
586 of an
587 \addtoindexi{address}{size of an address}
588 on the target architecture (or equivalently, target machine)
589 to which a DWARF description applies. For processors which
590 can be configured to have different address sizes or different
591 instruction sets, the intent is to refer to the configuration
592 which is either the default for that processor or which is
593 specified by the object file or executable file which contains
594 the DWARF information.
595
596 \textit{%
597 For example, if a particular target architecture supports
598 both 32\dash bit and 64\dash bit addresses, the compiler will generate
599 an object file which specifies that it contains executable
600 code generated for one or the other of these 
601 \addtoindexx{size of an address}
602 address sizes. In
603 that case, the DWARF debugging information contained in this
604 object file will use the same address size.
605 }
606
607 \textit{%
608 Architectures which have multiple instruction sets are
609 supported by the isa entry in the line number information
610 (see Section \refersec{chap:statemachineregisters}).
611 }
612
613 \section{DWARF Expressions}
614 \label{chap:dwarfexpressions}
615 DWARF expressions describe how to compute a value or name a
616 location during debugging of a program. 
617 They are expressed in
618 terms of DWARF operations that operate on a stack of values.
619
620 All DWARF operations are encoded as a stream of opcodes that
621 are each followed by zero or more literal operands. 
622 The number
623 of operands is determined by the opcode.  
624
625 In addition to the
626 general operations that are defined here, operations that are
627 specific to location descriptions are defined in 
628 Section \refersec{chap:locationdescriptions}.
629
630 \subsection{General Operations}
631 \label{chap:generaloperations}
632 Each general operation represents a postfix operation on
633 a simple stack machine. Each element of the stack is the
634 \addtoindex{size of an address} on the target machine. 
635 The value on the
636 top of the stack after \doublequote{executing} the 
637 \addtoindex{DWARF expression}
638 is 
639 \addtoindexx{DWARF expression|see{location description}}
640 taken to be the result (the address of the object, the
641 value of the array bound, the length of a dynamic string,
642 the desired value itself, and so on).
643
644 \subsubsection{Literal Encodings}
645 \label{chap:literalencodings}
646 The 
647 \addtoindexx{DWARF expression!literal encodings}
648 following operations all push a value onto the DWARF
649 stack. 
650 \addtoindexx{DWARF expression!stack operations}
651 If the value of a constant in one of these operations
652 is larger than can be stored in a single stack element, the
653 value is truncated to the element size and the low\dash order bits
654 are pushed on the stack.
655 \begin{enumerate}[1. ]
656 \itembfnl{\DWOPlitzeroTARG, \DWOPlitoneTARG, \dots, \DWOPlitthirtyoneTARG}
657 The \DWOPlitnTARG{} operations encode the unsigned literal values
658 from 0 through 31, inclusive.
659
660 \itembfnl{\DWOPaddrTARG}
661 The \DWOPaddrTARG{} operation has a single operand that encodes
662 a machine address and whose size is the \addtoindex{size of an address}
663 on the target machine.
664
665 \itembfnl{DWOPconstoneuTARG, \DWOPconsttwouTARG, \DWOPconstfouruTARG, \DWOPconsteightuTARG}
666 \DWOPconstnxMARK\DWOPconstnxINDX{}
667 The single operand of a \DWOPconstnuTARG{} operation provides a 1,
668 2, 4, or 8\dash byte unsigned integer constant, respectively.
669
670 \itembfnl{\DWOPconstonesTARG, \DWOPconsttwosTARG, \DWOPconstfoursTARG, \DWOPconsteightsTARG}
671 The single operand of a \DWOPconstnsTARG{} operation provides a 1,
672 2, 4, or 8\dash byte signed integer constant, respectively.
673
674 \itembfnl{\DWOPconstuTARG}
675 The single operand of the \DWOPconstuTARG{} operation provides
676 an unsigned LEB128 integer constant.
677
678 \itembfnl{\DWOPconstsTARG}
679 The single operand of the \DWOPconstsTARG{} operation provides
680 a signed LEB128 integer constant.
681
682 \end{enumerate}
683
684
685 \subsubsection{Register Based Addressing}
686 \label{chap:registerbasedaddressing}
687 The following operations push a value onto the stack that is
688 \addtoindexx{DWARF expression!register based addressing}
689 the result of adding the contents of a register to a given
690 signed offset.
691 \begin{enumerate}[1. ]
692 \itembfnl{\DWOPfbregTARG}
693 The \DWOPfbregTARG{} operation provides a signed LEB128 offset
694 from the address specified by the location description in the
695 \DWATframebase{} attribute of the current function. (This
696 is typically a \doublequote{stack pointer} register plus or minus
697 some offset. On more sophisticated systems it might be a
698 location list that adjusts the offset according to changes
699 in the stack pointer as the PC changes.)
700
701 \itembfnl{\DWOPbregzeroTARG, \DWOPbregoneTARG, \dots, \DWOPbregthirtyoneTARG}
702 The single operand of the \DWOPbregnTARG{} 
703 operations provides
704 a signed LEB128 offset from
705 the specified register.
706
707 \itembfnl{\DWOPbregxTARG{} }
708 The \DWOPbregxINDX{} operation has two operands: a register
709 which is specified by an unsigned LEB128 number, followed by
710 a signed LEB128 offset.
711
712 \end{enumerate}
713
714
715 \subsubsection{Stack Operations}
716 \label{chap:stackoperations}
717 The following 
718 \addtoindexx{DWARF expression!stack operations}
719 operations manipulate the DWARF stack. Operations
720 that index the stack assume that the top of the stack (most
721 recently added entry) has index 0.
722 \begin{enumerate}[1. ]
723 \itembfnl{\DWOPdupTARG}
724 The \DWOPdupTARG{} operation duplicates the value at the top of the stack.
725
726 \itembfnl{\DWOPdropTARG}
727 The \DWOPdropTARG{} operation pops the value at the top of the stack.
728
729 \itembfnl{\DWOPpickTARG}
730 The single operand of the \DWOPpickTARG{} operation provides a
731 1\dash byte index. A copy of the stack entry with the specified
732 index (0 through 255, inclusive) is pushed onto the stack.
733
734 \itembfnl{\DWOPoverTARG}
735 The \DWOPoverTARG{} operation duplicates the entry currently second
736 in the stack at the top of the stack. 
737 This is equivalent to
738 a \DWOPpick{} operation, with index 1.  
739
740 \itembfnl{\DWOPswapTARG}
741 The \DWOPswapTARG{} operation swaps the top two stack entries. 
742 The entry at the top of the
743 stack becomes the second stack entry, 
744 and the second entry becomes the top of the stack.
745
746 \itembfnl{\DWOProtTARG}
747 The \DWOProtTARG{} operation rotates the first three stack
748 entries. The entry at the top of the stack becomes the third
749 stack entry, the second entry becomes the top of the stack,
750 and the third entry becomes the second entry.
751
752 \itembfnl{\DWOPderefTARG}
753 The \DWOPderefTARG{} 
754 operation  pops the top stack entry and 
755 treats it as an address. The value
756 retrieved from that address is pushed. 
757 The size of the data retrieved from the 
758 \addtoindexi{dereferenced}{address!dereference operator}
759 address is the \addtoindex{size of an address} on the target machine.
760
761 \itembfnl{\DWOPderefsizeTARG}
762 The \DWOPderefsizeTARG{} operation behaves like the 
763 \DWOPderef{}
764 operation: it pops the top stack entry and treats it as an
765 address. The value retrieved from that address is pushed. In
766 the \DWOPderefsizeINDX{} operation, however, the size in bytes
767 of the data retrieved from the dereferenced address is
768 specified by the single operand. This operand is a 1\dash byte
769 unsigned integral constant whose value may not be larger
770 than the \addtoindex{size of an address} on the target machine. The data
771 retrieved is zero extended to the size of an address on the
772 target machine before being pushed onto the expression stack.
773
774 \needlines{7}
775 \itembfnl{\DWOPxderefTARG}
776 The \DWOPxderefTARG{} operation provides an extended dereference
777 mechanism. The entry at the top of the stack is treated as an
778 address. The second stack entry is treated as an \doublequote{address
779 space identifier} for those architectures that support
780 \addtoindexi{multiple}{address space!multiple}
781 address spaces. The top two stack elements are popped,
782 and a data item is retrieved through an implementation-defined
783 address calculation and pushed as the new stack top. The size
784 of the data retrieved from the 
785 \addtoindexi{dereferenced}{address!dereference operator}
786 address is the
787 \addtoindex{size of an address} on the target machine.
788
789 \itembfnl{\DWOPxderefsizeTARG}
790 The \DWOPxderefsizeTARG{} operation behaves like the
791 \DWOPxderef{} operation. The entry at the top of the stack is
792 treated as an address. The second stack entry is treated as
793 an \doublequote{address space identifier} for those architectures
794 that support 
795 \addtoindexi{multiple}{address space!multiple}
796 address spaces. The top two stack
797 elements are popped, and a data item is retrieved through an
798 implementation\dash defined address calculation and pushed as the
799 new stack top. In the \DWOPxderefsizeINDX{} operation, however,
800 the size in bytes of the data retrieved from the 
801 \addtoindexi{dereferenced}{address!dereference operator}
802 address is specified by the single operand. This operand is a
803 1\dash byte unsigned integral constant whose value may not be larger
804 than the \addtoindex{size of an address} on the target machine. The data
805 retrieved is zero extended to the \addtoindex{size of an address} on the
806 target machine before being pushed onto the expression stack.
807
808 \itembfnl{\DWOPpushobjectaddressTARG}
809 The \DWOPpushobjectaddressTARG{}
810 operation pushes the address
811 of the object currently being evaluated as part of evaluation
812 of a user presented expression. This object may correspond
813 to an independent variable described by its own debugging
814 information entry or it may be a component of an array,
815 structure, or class whose address has been dynamically
816 determined by an earlier step during user expression
817 evaluation.
818
819 \textit{This operator provides explicit functionality
820 (especially for arrays involving descriptors) that is analogous
821 to the implicit push of the base 
822 \addtoindexi{address}{address!implicit push of base}
823 of a structure prior to evaluation of a 
824 \DWATdatamemberlocation{} 
825 to access a data member of a structure. For an example, see 
826 Appendix \refersec{app:aggregateexamples}.}
827
828 \needlines{4}
829 \itembfnl{\DWOPformtlsaddressTARG}
830 The \DWOPformtlsaddressTARG{} 
831 operation pops a value from the stack, translates this
832 value into an address in the 
833 \addtoindexx{thread-local storage}
834 thread\dash local storage for a thread, and pushes the address 
835 onto the stack. 
836 The meaning of the value on the top of the stack prior to this 
837 operation is defined by the run-time environment.  If the run-time 
838 environment supports multiple thread\dash local storage 
839 \nolink{blocks} for a single thread, then the \nolink{block} 
840 corresponding to the executable or shared 
841 library containing this DWARF expression is used.
842    
843 \textit{Some implementations of 
844 \addtoindex{C} and \addtoindex{C++} support a
845 thread\dash local storage class. Variables with this storage class
846 have distinct values and addresses in distinct threads, much
847 as automatic variables have distinct values and addresses in
848 each function invocation. Typically, there is a single \nolink{block}
849 of storage containing all thread\dash local variables declared in
850 the main executable, and a separate \nolink{block} for the variables
851 declared in each shared library. 
852 Each thread\dash local variable can then be accessed in its block using an
853 identifier. This identifier is typically an offset into the block and pushed
854 onto the DWARF stack by one of the 
855 \DWOPconstnx{} operations prior to the
856 \DWOPformtlsaddress{} operation. 
857 Computing the address of
858 the appropriate \nolink{block} can be complex (in some cases, the
859 compiler emits a function call to do it), and difficult
860 to describe using ordinary DWARF location descriptions.
861 Instead of    forcing complex thread-local storage calculations into 
862 the DWARF expressions, the \DWOPformtlsaddress{} allows the consumer 
863 to perform the computation based on the run-time environment.}
864
865 \itembfnl{\DWOPcallframecfaTARG}
866 The \DWOPcallframecfaTARG{} 
867 operation pushes the value of the
868 CFA, obtained from the Call Frame Information 
869 (see Section \refersec{chap:callframeinformation}).
870
871 \textit{Although the value of \DWATframebase{}
872 can be computed using other DWARF expression operators,
873 in some cases this would require an extensive location list
874 because the values of the registers used in computing the
875 CFA change during a subroutine. If the 
876 Call Frame Information 
877 is present, then it already encodes such changes, and it is
878 space efficient to reference that.}
879 \end{enumerate}
880
881 \subsubsection{Arithmetic and Logical Operations}
882 The 
883 \addtoindexx{DWARF expression!arithmetic operations}
884 following 
885 \addtoindexx{DWARF expression!logical operations}
886 provide arithmetic and logical operations. Except
887 as otherwise specified, the arithmetic operations perfom
888 addressing arithmetic, that is, unsigned arithmetic that is
889 performed modulo one plus the largest representable address
890 (for example, 0x100000000 when the 
891 \addtoindex{size of an address} is 32 bits). 
892 Such operations do not cause an exception on overflow.
893
894 \needlines{4}
895 \begin{enumerate}[1. ]
896 \itembfnl{\DWOPabsTARG}
897 The \DWOPabsTARG{} operation pops the top stack entry, interprets
898 it as a signed value and pushes its absolute value. If the
899 absolute value cannot be represented, the result is undefined.
900
901 \needlines{4}
902 \itembfnl{\DWOPandTARG}
903 The \DWOPandTARG{} operation pops the top two stack values, performs
904 a bitwise and operation on the two, and pushes the result.
905
906 \itembfnl{\DWOPdivTARG}
907 The \DWOPdivTARG{} operation pops the top two stack values, divides the former second entry by
908 the former top of the stack using signed division, and pushes the result.
909
910 \itembfnl{\DWOPminusTARG}
911 The \DWOPminusTARG{} operation pops the top two stack values, subtracts the former top of the
912 stack from the former second entry, and pushes the result.
913
914 \itembfnl{\DWOPmodTARG}
915 The \DWOPmodTARG{} operation pops the top two stack values and pushes the result of the
916 calculation: former second stack entry modulo the former top of the stack.
917
918 \itembfnl{\DWOPmulTARG}
919 The \DWOPmulTARG{} operation pops the top two stack entries, multiplies them together, and
920 pushes the result.
921
922 \itembfnl{\DWOPnegTARG}
923 The \DWOPnegTARG{} operation pops the top stack entry, interprets
924 it as a signed value and pushes its negation. If the negation
925 cannot be represented, the result is undefined.
926
927 \itembfnl{\DWOPnotTARG}
928 The \DWOPnotTARG{} operation pops the top stack entry, and pushes
929 its bitwise complement.
930
931 \itembfnl{\DWOPorTARG}
932 The \DWOPorTARG{} operation pops the top two stack entries, performs
933 a bitwise or operation on the two, and pushes the result.
934
935 \itembfnl{\DWOPplusTARG}
936 The \DWOPplusTARG{} operation pops the top two stack entries,
937 adds them together, and pushes the result.
938
939 \itembfnl{\DWOPplusuconstTARG}
940 The \DWOPplusuconstTARG{} operation pops the top stack entry,
941 adds it to the unsigned LEB128 constant operand and pushes
942 the result.
943
944 \textit{This operation is supplied specifically to be
945 able to encode more field offsets in two bytes than can be
946 done with
947 \doublequote{\DWOPlitn~\DWOPplus.}}
948
949 \needlines{3}
950 \itembfnl{\DWOPshlTARG}
951 The \DWOPshlTARG{} operation pops the top two stack entries,
952 shifts the former second entry left (filling with zero bits)
953 by the number of bits specified by the former top of the stack,
954 and pushes the result.
955
956 \itembfnl{\DWOPshrTARG}
957 The \DWOPshrTARG{} operation pops the top two stack entries,
958 shifts the former second entry right logically (filling with
959 zero bits) by the number of bits specified by the former top
960 of the stack, and pushes the result.
961
962 \needlines{6}
963 \itembfnl{\DWOPshraTARG}
964 The \DWOPshraTARG{} operation pops the top two stack entries,
965 shifts the former second entry right arithmetically (divide
966 the magnitude by 2, keep the same sign for the result) by
967 the number of bits specified by the former top of the stack,
968 and pushes the result.
969
970 \itembfnl{\DWOPxorTARG}
971 The \DWOPxorTARG{} operation pops the top two stack entries,
972 performs a bitwise exclusive\dash or operation on the two, and
973 pushes the result.
974
975 \end{enumerate}
976
977 \subsubsection{Control Flow Operations}
978 \label{chap:controlflowoperations}
979 The 
980 \addtoindexx{DWARF expression!control flow operations}
981 following operations provide simple control of the flow of a DWARF expression.
982 \begin{enumerate}[1. ]
983 \itembfnl{\DWOPleTARG, \DWOPgeTARG, \DWOPeqTARG, \DWOPltTARG, \DWOPgtTARG, \DWOPneTARG}
984 The six relational operators each:
985 \begin{itemize}
986 \item pop the top two stack values,
987
988 \item compare the operands:
989 \linebreak
990 \textless~former second entry~\textgreater  \textless~relational operator~\textgreater \textless~former top entry~\textgreater
991
992 \item push the constant value 1 onto the stack 
993 if the result of the operation is true or the
994 constant value 0 if the result of the operation is false.
995 \end{itemize}
996
997 Comparisons are performed as signed operations. The six
998 operators are \DWOPleINDX{} (less than or equal to), \DWOPgeINDX{}
999 (greater than or equal to), \DWOPeqINDX{} (equal to), \DWOPltINDX{} (less
1000 than), \DWOPgtINDX{} (greater than) and \DWOPneINDX{} (not equal to).
1001
1002 \needlines{6}
1003 \itembfnl{\DWOPskipTARG}
1004 \DWOPskipTARG{} is an unconditional branch. Its single operand
1005 is a 2\dash byte signed integer constant. The 2\dash byte constant is
1006 the number of bytes of the DWARF expression to skip forward
1007 or backward from the current operation, beginning after the
1008 2\dash byte constant.
1009
1010 \itembfnl{\DWOPbraTARG}
1011 \DWOPbraTARG{} is a conditional branch. Its single operand is a
1012 2\dash byte signed integer constant.  This operation pops the
1013 top of stack. If the value popped is not the constant 0,
1014 the 2\dash byte constant operand is the number of bytes of the
1015 DWARF expression to skip forward or backward from the current
1016 operation, beginning after the 2\dash byte constant.
1017
1018 % The following item does not correctly hyphenate leading
1019 % to an overfull hbox and a visible artifact. 
1020 % So we use \- to suggest hyphenation in this rare situation.
1021 \itembfnl{\DWOPcalltwoTARG, \DWOPcallfour, \DWOPcallrefTARG}
1022 \DWOPcalltwoINDX, 
1023 \DWOPcallfourINDX, 
1024 and \DWOPcallrefINDX{} perform
1025 subroutine calls during evaluation of a DWARF expression or
1026 location description. 
1027 For \DWOPcalltwoINDX{} and \DWOPcallfour{}, 
1028 the operand is the 2\dash~ or 4\dash byte unsigned offset, respectively,
1029 of a debugging information entry in the current compilation
1030 unit. The \DWOPcallref{} operator has a single operand. In the
1031 \thirtytwobitdwarfformat,
1032 the operand is a 4\dash byte unsigned value;
1033 in the \sixtyfourbitdwarfformat, it is an 8\dash byte unsigned value
1034 (see Section \refersec{datarep:32bitand64bitdwarfformats}). 
1035 The operand is used as the offset of a
1036 debugging information entry in a 
1037 \dotdebuginfo{}
1038 or
1039 \dotdebugtypes{}
1040 section which may be contained in a shared object or executable
1041 other than that containing the operator. For references from
1042 one shared object or executable to another, the relocation
1043 must be performed by the consumer.  
1044
1045 \textit{Operand interpretation of
1046 \DWOPcalltwo, \DWOPcallfour{} and \DWOPcallref{} is exactly like
1047 that for \DWFORMreftwo, \DWFORMreffour{} and \DWFORMrefaddr,
1048 respectively  
1049 (see Section  \refersec{datarep:attributeencodings}).  
1050 }
1051
1052 These operations transfer
1053 control of DWARF expression evaluation to 
1054 \addtoindexx{location attribute}
1055 the 
1056 \DWATlocation{}
1057 attribute of the referenced debugging information entry. If
1058 there is no such attribute, then there is no effect. Execution
1059 of the DWARF expression of 
1060 \addtoindexx{location attribute}
1061
1062 \DWATlocation{} attribute may add
1063 to and/or remove from values on the stack. Execution returns
1064 to the point following the call when the end of the attribute
1065 is reached. Values on the stack at the time of the call may be
1066 used as parameters by the called expression and values left on
1067 the stack by the called expression may be used as return values
1068 by prior agreement between the calling and called expressions.
1069 \end{enumerate}
1070
1071 \needlines{7}
1072 \subsubsection{Special Operations}
1073 There 
1074 \addtoindexx{DWARF expression!special operations}
1075 is one special operation currently defined:
1076 \begin{enumerate}[1. ]
1077 \itembfnl{\DWOPnopTARG}
1078 The \DWOPnopTARG{} operation is a place holder. It has no effect
1079 on the location stack or any of its values.
1080 \end{enumerate}
1081
1082 \subsection{Example Stack Operations}
1083 \textit {The 
1084 \addtoindexx{DWARF expression!examples}
1085 stack operations defined in 
1086 Section \refersec{chap:stackoperations}.
1087 are fairly conventional, but the following
1088 examples illustrate their behavior graphically.}
1089
1090 \begin{longtable}[c]{rrcrr} 
1091 \multicolumn{2}{c}{Before} & Operation & \multicolumn{2}{c}{After} \\
1092 \hline
1093 \endhead
1094 \endfoot
1095 0& 17& \DWOPdup{} &0 &17 \\
1096 1&   29& &  1 & 17 \\
1097 2& 1000 & & 2 & 29\\
1098 & & &         3&1000\\
1099
1100 & & & & \\
1101 0 & 17 & \DWOPdrop{} & 0 & 29 \\
1102 1 &29  &            & 1 & 1000 \\
1103 2 &1000& & &          \\
1104
1105 & & & & \\
1106 0 & 17 & \DWOPpick, 2 & 0 & 1000 \\
1107 1 & 29 & & 1&17 \\
1108 2 &1000& &2&29 \\
1109   &    & &3&1000 \\
1110
1111 & & & & \\
1112 0&17& \DWOPover&0&29 \\
1113 1&29& &  1&17 \\
1114 2&1000 & & 2&29\\
1115  &     & & 3&1000 \\
1116
1117 & & & & \\
1118 0&17& \DWOPswap{} &0&29 \\
1119 1&29& &  1&17 \\
1120 2&1000 & & 2&1000 \\
1121
1122 & & & & \\
1123 0&17&\DWOProt{} & 0 &29 \\
1124 1&29 & & 1 & 1000 \\
1125 2& 1000 & &  2 & 17 \\
1126 \end{longtable}
1127
1128 \section{Location Descriptions}
1129 \label{chap:locationdescriptions}
1130 \textit{Debugging information 
1131 \addtoindexx{location description}
1132 must 
1133 \addtoindexx{location description|see{\textit{also} DWARF expression}}
1134 provide consumers a way to find
1135 the location of program variables, determine the bounds
1136 of dynamic arrays and strings, and possibly to find the
1137 base address of a subroutine\textquoteright s stack frame or the return
1138 address of a subroutine. Furthermore, to meet the needs of
1139 recent computer architectures and optimization techniques,
1140 debugging information must be able to describe the location of
1141 an object whose location changes over the object\textquoteright s lifetime.}
1142
1143 Information about the location of program objects is provided
1144 by location descriptions. Location descriptions can be either
1145 of two forms:
1146 \begin{enumerate}[1. ]
1147 \item \textit{Single location descriptions}, 
1148 which 
1149 \addtoindexx{location description!single}
1150 are 
1151 \addtoindexx{single location description}
1152 a language independent representation of
1153 addressing rules of arbitrary complexity built from 
1154 DWARF expressions (See Section \refersec{chap:dwarfexpressions}) 
1155 and/or other
1156 DWARF operations specific to describing locations. They are
1157 sufficient for describing the location of any object as long
1158 as its lifetime is either static or the same as the 
1159 \livelink{chap:lexicalblock}{lexical block} that owns it, 
1160 and it does not move during its lifetime.
1161
1162 Single location descriptions are of two kinds:
1163 \begin{enumerate}[a) ]
1164 \item Simple location descriptions, which describe the location
1165 \addtoindexx{location description!simple}
1166 of one contiguous piece (usually all) of an object. A simple
1167 location description may describe a location in addressable
1168 memory, or in a register, or the lack of a location (with or
1169 without a known value).
1170
1171 \item  Composite location descriptions, which describe an
1172 \addtoindexx{location description!composite}
1173 object in terms of pieces each of which may be contained in
1174 part of a register or stored in a memory location unrelated
1175 to other pieces.
1176
1177 \end{enumerate}
1178 \item \textit{Location lists}, which are used to 
1179 \addtoindexx{location list}
1180 describe
1181 \addtoindexx{location description!use in location list}
1182 objects that have a limited lifetime or change their location
1183 during their lifetime. Location lists are more completely
1184 described below.
1185
1186 \end{enumerate}
1187
1188 The two forms are distinguished in a context sensitive
1189 manner. As the value of an attribute, a location description
1190 is encoded using 
1191 \addtoindexx{exprloc class}
1192 class \livelink{chap:classexprloc}{exprloc}  
1193 and a location list is encoded
1194 using class \livelink{chap:classloclistptr}{loclistptr}
1195 (which 
1196 \addtoindex{loclistptr}
1197 serves as an offset into a
1198 separate 
1199 \addtoindexx{location list}
1200 location list table).
1201
1202
1203 \subsection{Single Location Descriptions}
1204 A single location description is either:
1205 \begin{enumerate}[1. ]
1206 \item A simple location description, representing an object
1207 \addtoindexx{location description!simple}
1208 which 
1209 \addtoindexx{simple location description}
1210 exists in one contiguous piece at the given location, or 
1211 \item A composite location description consisting of one or more
1212 \addtoindexx{location description!composite}
1213 simple location descriptions, each of which is followed by
1214 one composition operation. Each simple location description
1215 describes the location of one piece of the object; each
1216 composition operation describes which part of the object is
1217 located there. Each simple location description that is a
1218 DWARF expression is evaluated independently of any others
1219 (as though on its own separate stack, if any). 
1220 \end{enumerate}
1221
1222
1223
1224 \subsubsection{Simple Location Descriptions}
1225
1226
1227 \addtoindexx{location description!simple}
1228 simple location description consists of one 
1229 contiguous piece or all of an object or value.
1230
1231
1232 \subsubsubsection{Memory Location Descriptions}
1233
1234 \addtoindexx{location description!memory}
1235 memory location description 
1236 \addtoindexx{memory location description}
1237 consists of a non\dash empty DWARF
1238 expression (see 
1239 Section \refersec{chap:dwarfexpressions}
1240 ), whose value is the address of
1241 a piece or all of an object or other entity in memory.
1242
1243 \subsubsubsection{Register Location Descriptions}
1244 A register location description consists of a register name
1245 operation, which represents a piece or all of an object
1246 located in a given register.
1247
1248 \textit{Register location descriptions describe an object
1249 (or a piece of an object) that resides in a register, while
1250 the opcodes listed in 
1251 Section \refersec{chap:registerbasedaddressing}
1252 are used to describe an object (or a piece of
1253 an object) that is located in memory at an address that is
1254 contained in a register (possibly offset by some constant). A
1255 register location description must stand alone as the entire
1256 description of an object or a piece of an object.
1257 }
1258
1259 The following DWARF operations can be used to name a register.
1260
1261
1262 \textit{Note that the register number represents a DWARF specific
1263 mapping of numbers onto the actual registers of a given
1264 architecture. The mapping should be chosen to gain optimal
1265 density and should be shared by all users of a given
1266 architecture. It is recommended that this mapping be defined
1267 by the ABI authoring committee for each architecture.
1268 }
1269 \begin{enumerate}[1. ]
1270 \itembfnl{\DWOPregzeroTARG, \DWOPregoneTARG, ..., \DWOPregthirtyoneTARG}
1271 The \DWOPregnTARG{} operations encode the names of up to 32
1272 registers, numbered from 0 through 31, inclusive. The object
1273 addressed is in register \textit{n}.
1274
1275 \needlines{4}
1276 \itembfnl{\DWOPregxTARG}
1277 The \DWOPregxTARG{} operation has a single unsigned LEB128 literal
1278 operand that encodes the name of a register.  
1279
1280 \end{enumerate}
1281
1282 \textit{These operations name a register location. To
1283 fetch the contents of a register, it is necessary to use
1284 one of the register based addressing operations, such as
1285 \DWOPbregx{} 
1286 (Section \refersec{chap:registerbasedaddressing})}.
1287
1288 \subsubsubsection{Implicit Location Descriptions}
1289 An \addtoindex{implicit location description}
1290 represents a piece or all
1291 \addtoindexx{location description!implicit}
1292 of an object which has no actual location but whose contents
1293 are nonetheless either known or known to be undefined.
1294
1295 The following DWARF operations may be used to specify a value
1296 that has no location in the program but is a known constant
1297 or is computed from other locations and values in the program.
1298
1299 The following DWARF operations may be used to specify a value
1300 that has no location in the program but is a known constant
1301 or is computed from other locations and values in the program.
1302 \begin{enumerate}[1. ]
1303 \itembfnl{\DWOPimplicitvalueTARG}
1304 The \DWOPimplicitvalueTARG{} 
1305 operation specifies an immediate value
1306 using two operands: an unsigned LEB128 length, followed by
1307 %FIXME: should this block be a reference? To what?
1308 a \nolink{block} representing the value in the memory representation
1309 of the target machine. The length operand gives the length
1310 in bytes of the \nolink{block}.
1311
1312 \itembfnl{\DWOPstackvalueTARG}
1313 The \DWOPstackvalueTARG{} 
1314 operation specifies that the object
1315 does not exist in memory but its value is nonetheless known
1316 and is at the top of the DWARF expression stack. In this form
1317 of location description, the DWARF expression represents the
1318 actual value of the object, rather than its location. The
1319 \DWOPstackvalueINDX{} operation terminates the expression.
1320 \end{enumerate}
1321
1322
1323 \paragraph{Empty Location Descriptions}
1324
1325 An \addtoindex{empty location description}
1326 consists of a DWARF expression
1327 \addtoindexx{location description!empty}
1328 containing no operations. It represents a piece or all of an
1329 object that is present in the source but not in the object code
1330 (perhaps due to optimization).
1331
1332 \needlines{5}
1333 \subsubsection{Composite Location Descriptions}
1334 A composite location description describes an object or
1335 value which may be contained in part of a register or stored
1336 in more than one location. Each piece is described by a
1337 composition operation, which does not compute a value nor
1338 store any result on the DWARF stack. There may be one or
1339 more composition operations in a single composite location
1340 description. A series of such operations describes the parts
1341 of a value in memory address order.
1342
1343 Each composition operation is immediately preceded by a simple
1344 location description which describes the location where part
1345 of the resultant value is contained.
1346 \begin{enumerate}[1. ]
1347 \itembfnl{\DWOPpieceTARG}
1348 The \DWOPpieceTARG{} operation takes a 
1349 single operand, which is an
1350 unsigned LEB128 number.  The number describes the size in bytes
1351 of the piece of the object referenced by the preceding simple
1352 location description. If the piece is located in a register,
1353 but does not occupy the entire register, the placement of
1354 the piece within that register is defined by the ABI.
1355
1356 \textit{Many compilers store a single variable in sets of registers,
1357 or store a variable partially in memory and partially in
1358 registers. \DWOPpieceINDX{} provides a way of describing how large
1359 a part of a variable a particular DWARF location description
1360 refers to. }
1361
1362 \itembfnl{\DWOPbitpieceTARG}
1363 The \DWOPbitpieceTARG{} 
1364 operation takes two operands. The first
1365 is an unsigned LEB128 number that gives the size in bits
1366 of the piece. The second is an unsigned LEB128 number that
1367 gives the offset in bits from the location defined by the
1368 preceding DWARF location description.  
1369
1370 Interpretation of the
1371 offset depends on the kind of location description. If the
1372 location description is empty, the offset doesn\textquoteright t matter and
1373 the \DWOPbitpieceINDX{} operation describes a piece consisting
1374 of the given number of bits whose values are undefined. If
1375 the location is a register, the offset is from the least
1376 significant bit end of the register. If the location is a
1377 memory address, the \DWOPbitpieceINDX{} operation describes a
1378 sequence of bits relative to the location whose address is
1379 on the top of the DWARF stack using the bit numbering and
1380 direction conventions that are appropriate to the current
1381 language on the target system. If the location is any implicit
1382 value or stack value, the \DWOPbitpieceINDX{} operation describes
1383 a sequence of bits using the least significant bits of that
1384 value.  
1385 \end{enumerate}
1386
1387 \textit{\DWOPbitpieceINDX{} is 
1388 used instead of \DWOPpieceINDX{} when
1389 the piece to be assembled into a value or assigned to is not
1390 byte-sized or is not at the start of a register or addressable
1391 unit of memory.}
1392
1393
1394
1395
1396 \subsubsection{Example Single Location Descriptions}
1397
1398 Here are some examples of how DWARF operations are used to form location descriptions:
1399 % Probably the only place that this will be used, so not in dwarf.tex?
1400 \newcommand{\descriptionitemnl}[1]{\item[#1]\mbox{}\\}
1401 \begin{description}
1402 \descriptionitemnl{\DWOPregthree}
1403 The value is in register 3.
1404
1405 \descriptionitemnl{\DWOPregx{} 54}
1406 The value is in register 54.
1407
1408 \descriptionitemnl{\DWOPaddr{} 0x80d0045c}
1409 The value of a static variable is at machine address 0x80d0045c.
1410
1411 \descriptionitemnl{\DWOPbregeleven{} 44}
1412 Add 44 to the value in register 11 to get the address of an automatic
1413 variable instance.
1414
1415 \descriptionitemnl{\DWOPfbreg{} -50}
1416 Given a \DWATframebase{} value of
1417 \doublequote{\DWOPbregthirtyone{} 64,} this example
1418 computes the address of a local variable that is -50 bytes from a
1419 logical frame pointer that is computed by adding 64 to the current
1420 stack pointer (register 31).
1421
1422 \descriptionitemnl{\DWOPbregx{} 54 32 \DWOPderef}
1423 A call-by-reference parameter whose address is in the word 32 bytes
1424 from where register 54 points.
1425
1426 \descriptionitemnl{\DWOPplusuconst{} 4}
1427 A structure member is four bytes from the start of the structure
1428 instance. The base address is assumed to be already on the stack.
1429
1430 \descriptionitemnl{\DWOPregthree{} \DWOPpiece{} 4 \DWOPregten{} \DWOPpiece{} 2}
1431 A variable whose first four bytes reside in register 3 and whose next
1432 two bytes reside in register 10.
1433
1434 \descriptionitemnl{\DWOPregzero{} \DWOPpiece{} 4 \DWOPpiece{} 4 \DWOPfbreg{} -12 \DWOPpiece{} 4}
1435 A twelve byte value whose first four bytes reside in register zero,
1436 whose middle four bytes are unavailable (perhaps due to optimization),
1437 and whose last four bytes are in memory, 12 bytes before the frame
1438 base.
1439
1440 \descriptionitemnl{\DWOPbregone{} 0 \DWOPbregtwo{} 0 \DWOPplus{} \DWOPstackvalue{} }
1441 Add the contents of r1 and r2 to compute a value. This value is the
1442 \doublequote{contents} of an otherwise anonymous location.
1443
1444 \needlines{6}
1445 \descriptionitemnl{\DWOPlitone{} \DWOPstackvalue{} \DWOPpiece{} 4 }
1446 \vspace{-0.1\parsep}
1447 \descriptionitemnl{\DWOPbregthree 0 \DWOPbregfour 0 \DWOPplus{} \DWOPstackvalue{} \DWOPpiece{} 4}
1448 The object value is found in an anonymous (virtual) location whose
1449 value consists of two parts, given in memory address order: the 4 byte
1450 value 1 followed by the four byte value computed from the sum of the
1451 contents of r3 and r4.
1452 \end{description}
1453
1454
1455 \subsection{Location Lists}
1456 \label{chap:locationlists}
1457 Location lists 
1458 \addtoindexx{location list}
1459 are used in place of location expressions
1460 whenever the object whose location is being described
1461 can change location during its lifetime. 
1462 Location lists
1463 \addtoindexx{location list}
1464 are contained in a separate object file section called
1465 \dotdebugloc{}. A location list is indicated by a location
1466 attribute whose value is an offset from the beginning of
1467 the \dotdebugloc{} section to the first byte of the list for the
1468 object in question.
1469
1470 Each entry in a location list is either a location 
1471 \addtoindexi{list}{address selection|see{base address selection}} 
1472 entry,
1473
1474 \addtoindexi{base}{base address selection entry!in location list} 
1475 address selection entry, 
1476 \addtoindexx{location list!base address selection entry}
1477 or an 
1478 \addtoindexx{end of list entry!in location list}
1479 end of list entry.
1480
1481 A location list entry has two forms:
1482 a normal location list entry and a default location list entry.
1483
1484
1485 \addtoindexx{location list!normal entry}
1486 normal location list entry consists of:
1487 \begin{enumerate}[1. ]
1488 \item A beginning address offset. 
1489 This address offset has the \addtoindex{size of an address} and is
1490 relative to the applicable base address of the compilation
1491 unit referencing this location list. It marks the beginning
1492 of the address 
1493 \addtoindexi{range}{address range!in location list} 
1494 over which the location is valid.
1495
1496 \item An ending address offset.  This address offset again
1497 has the \addtoindex{size of an address} and is relative to the applicable
1498 base address of the compilation unit referencing this location
1499 list. It marks the first address past the end of the address
1500 range over which the location is valid. The ending address
1501 must be greater than or equal to the beginning address.
1502
1503 \textit{A location list entry (but not a base address selection or 
1504 end of list entry) whose beginning
1505 and ending addresses are equal has no effect 
1506 because the size of the range covered by such
1507 an entry is zero.}
1508
1509 \item A 2-byte length describing the length of the location 
1510 description that follows.
1511
1512 \item A \addtoindex{single location description} 
1513 describing the location of the object over the range specified by
1514 the beginning and end addresses.
1515 \end{enumerate}
1516
1517 \needlines{5}
1518 The applicable base address of a normal
1519 location list entry is
1520 \addtoindexx{location list!base address selection entry}
1521 determined by the closest preceding base address selection
1522 entry (see below) in the same location list. If there is
1523 no such selection entry, then the applicable base address
1524 defaults to the base address of the compilation unit (see
1525 Section \refersec{chap:normalandpartialcompilationunitentries}).  
1526
1527 \textit{In the case of a compilation unit where all of
1528 the machine code is contained in a single contiguous section,
1529 no base address selection entry is needed.}
1530
1531 Address ranges defined by normal location list entries
1532 may overlap. When they do, they describe a
1533 situation in which an object exists simultaneously in more than
1534 one place. If all of the address ranges in a given location
1535 list do not collectively cover the entire range over which the
1536 object in question is defined, it is assumed that the object is
1537 not available for the portion of the range that is not covered.
1538
1539 A default location list entry consists of:
1540 \addtoindexx{location list!default entry}
1541 \begin{enumerate}[1. ]
1542 \item The value 0.
1543 \item The value of the largest representable address offset (for
1544       example, \wffffffff when the size of an address is 32 bits).
1545 \item A simple location description describing the location of the
1546       object when there is no prior normal location list entry
1547       that applies in the same location list.
1548 \end{enumerate}
1549
1550 A default location list entry is independent of any applicable
1551 base address (except to the extent to which base addresses
1552 affect prior normal location list entries).
1553
1554 A default location list entry must be the last location list
1555 entry of a location list except for the terminating end of list
1556 entry.
1557
1558 A default location list entry describes an unlimited number
1559 (zero, one or more) of address ranges, none of which overlap
1560 any of the address ranges defined earlier in the same location
1561 list. Further, all such address ranges have the same simple
1562 location.
1563
1564 \needlines{5}
1565 A base 
1566 \addtoindexi{address}{address selection|see{base address selection}}
1567 \addtoindexx{location list!base address selection entry}
1568 selection 
1569 \addtoindexi{entry}{base address selection entry!in location list}
1570 consists of:
1571 \begin{enumerate}[1. ]
1572 \item The value of the largest representable 
1573 address offset (for example, \wffffffff when the size of
1574 an address is 32 bits).
1575 \item An address, which defines the 
1576 appropriate base address for use in interpreting the beginning
1577 and ending address offsets of subsequent entries of the location list.
1578 \end{enumerate}
1579
1580 \textit{A base address selection entry 
1581 affects only the list in which it is contained.}
1582
1583 \needlines{5}
1584 The end of any given location list is marked by an 
1585 \addtoindexx{location list!end of list entry}
1586 end of list entry, which consists of a 0 for the beginning address
1587 offset and a 0 for the ending address offset. A location list
1588 containing only an 
1589 \addtoindexx{end of list entry!in location list}
1590 end of list entry describes an object that
1591 exists in the source code but not in the executable program.
1592
1593 Neither a base address selection entry nor an end of list
1594 entry includes a location description.
1595
1596 \textit{When a DWARF consumer is parsing and decoding a location
1597 list, it must recognize the beginning and ending address
1598 offsets of (0, 0) for an end of list entry and (0, \doublequote{-1}) for
1599 a default location list entry prior to applying any base
1600 address. Any other pair of offsets beginning with 0 is a
1601 valid normal location list entry. Next, it must recognize the
1602 beginning address offset of \doublequote{-1} for a base address selection
1603 entry prior to applying any base address. The current base
1604 address is not applied to the subsequent value (although there
1605 may be an underlying object language relocation that affects
1606 that value).}
1607
1608 \textit{A base address selection entry and an end of list
1609 entry for a location list are identical to a base address
1610 selection entry and end of list entry, respectively, for a
1611 \addtoindex{range list}
1612 (see Section \refersec{chap:noncontiguousaddressranges}) 
1613 in interpretation
1614 and representation.}
1615
1616
1617 \section{Types of Program Entities}
1618 \label{chap:typesofprogramentities}
1619 Any 
1620 \hypertarget{chap:DWATtypetypeofdeclaration}
1621 debugging information entry describing a declaration that
1622 has a type has 
1623 \addtoindexx{type attribute}
1624 a \DWATtype{} attribute, whose value is a
1625 reference to another debugging information entry. The entry
1626 referenced may describe a base type, that is, a type that is
1627 not defined in terms of other data types, or it may describe a
1628 user-defined type, such as an array, structure or enumeration.
1629 Alternatively, the entry referenced may describe a type
1630 modifier, such as constant, packed, pointer, reference or
1631 volatile, which in turn will reference another entry describing
1632 a type or type modifier (using 
1633 \addtoindexx{type attribute}
1634 a \DWATtype{} attribute of its
1635 own). See 
1636 Section  \refersec{chap:typeentries} 
1637 for descriptions of the entries describing
1638 base types, user-defined types and type modifiers.
1639
1640
1641
1642 \section{Accessibility of Declarations}
1643 \label{chap:accessibilityofdeclarations}
1644 \textit{Some languages, notably C++ and 
1645 \addtoindex{Ada}, have the concept of
1646 the accessibility of an object or of some other program
1647 entity. The accessibility specifies which classes of other
1648 program objects are permitted access to the object in question.}
1649
1650 The accessibility of a declaration is 
1651 \hypertarget{chap:DWATaccessibilitycandadadeclarations}
1652 represented by a 
1653 \DWATaccessibility{} 
1654 attribute, whose
1655 \addtoindexx{accessibility attribute}
1656 value is a constant drawn from the set of codes listed in Table 
1657 \refersec{tab:accessibilitycodes}.
1658
1659 \begin{simplenametable}[1.9in]{Accessibility codes}{tab:accessibilitycodes}
1660 \DWACCESSpublicTARG{}          \\
1661 \DWACCESSprivateTARG{}        \\
1662 \DWACCESSprotectedTARG{}    \\
1663 \end{simplenametable}
1664
1665 \section{Visibility of Declarations}
1666 \label{chap:visibilityofdeclarations}
1667
1668 \textit{Several languages (such as \addtoindex{Modula-2}) 
1669 have the concept of the visibility of a declaration. The
1670 visibility specifies which declarations are to be 
1671 visible outside of the entity in which they are
1672 declared.}
1673
1674 The 
1675 \hypertarget{chap:DWATvisibilityvisibilityofdeclaration}
1676 visibility of a declaration is represented 
1677 by a \DWATvisibility{}
1678 attribute\addtoindexx{visibility attribute}, whose value is a
1679 constant drawn from the set of codes listed in 
1680 Table \refersec{tab:visibilitycodes}.
1681
1682 \begin{simplenametable}[1.5in]{Visibility codes}{tab:visibilitycodes}
1683 \DWVISlocalTARG{}          \\
1684 \DWVISexportedTARG{}    \\
1685 \DWVISqualifiedTARG{}  \\
1686 \end{simplenametable}
1687
1688 \section{Virtuality of Declarations}
1689 \label{chap:virtualityofdeclarations}
1690 \textit{C++ provides for virtual and pure virtual structure or class
1691 member functions and for virtual base classes.}
1692
1693 The 
1694 \hypertarget{chap:DWATvirtualityvirtualityindication}
1695 virtuality of a declaration is represented by a
1696 \DWATvirtuality{}
1697 attribute\addtoindexx{virtuality attribute}, whose value is a constant drawn
1698 from the set of codes listed in 
1699 Table \refersec{tab:virtualitycodes}.
1700
1701 \begin{simplenametable}[2.4in]{Virtuality codes}{tab:virtualitycodes}
1702 \DWVIRTUALITYnoneTARG{}                      \\
1703 \DWVIRTUALITYvirtualTARG{}                \\
1704 \DWVIRTUALITYpurevirtualTARG{}    \\
1705 \end{simplenametable}
1706
1707 \section{Artificial Entries}
1708 \label{chap:artificialentries}
1709 \textit{A compiler may wish to generate debugging information entries
1710 for objects or types that were not actually declared in the
1711 source of the application. An example is a formal parameter
1712 %FIXME: The word 'this' should be rendered like a variant italic,
1713 %FIXME: not as a quoted name. Changed to tt font--RB
1714 entry to represent the 
1715 \texttt{this} parameter\index{this parameter@\texttt{this} parameter}
1716 hidden \texttt{this} parameter that most C++
1717 implementations pass as the first argument to non-static member
1718 functions.}  
1719
1720 Any debugging information entry representing the
1721 \addtoindexx{artificial attribute}
1722 declaration of an object or type artificially generated by
1723 a compiler and not explicitly declared by the source program
1724 \hypertarget{chap:DWATartificialobjectsortypesthat}
1725 may have a 
1726 \DWATartificial{} attribute, 
1727 which is a \livelink{chap:classflag}{flag}.
1728
1729 \section{Segmented Addresses}
1730 \label{chap:segmentedaddresses}
1731 \textit{In some systems, addresses are specified as offsets within a
1732 given 
1733 \addtoindexx{address space!segmented}
1734 segment 
1735 \addtoindexx{segmented addressing|see{address space}}
1736 rather than as locations within a single flat
1737 \addtoindexx{address space!flat}.
1738 address space.}
1739
1740 Any debugging information entry that contains a description
1741 \hypertarget{chap:DWATsegmentaddressinginformation}
1742 of the location of an object or subroutine may have
1743
1744 \DWATsegment{} attribute, 
1745 \addtoindexx{segment attribute}
1746 whose value is a location
1747 description. The description evaluates to the segment selector
1748 of the item being described. If the entry containing the
1749 \DWATsegment{} attribute has a 
1750 \DWATlowpc, 
1751 \DWAThighpc,
1752 \DWATranges{} or 
1753 \DWATentrypc{} attribute, 
1754 \addtoindexx{entry pc attribute}
1755 or 
1756 a location
1757 description that evaluates to an address, then those address
1758 values represent the offset portion of the address within
1759 the segment specified 
1760 \addtoindexx{segment attribute}
1761 by \DWATsegment.
1762
1763 If an entry has no 
1764 \DWATsegment{} attribute, it inherits
1765 \addtoindexx{segment attribute}
1766 the segment value from its parent entry.  If none of the
1767 entries in the chain of parents for this entry back to
1768 its containing compilation unit entry have 
1769 \DWATsegment{} attributes, 
1770 then the entry is assumed to exist within a flat
1771 address space. 
1772 Similarly, if the entry has a 
1773 \DWATsegment{} attribute 
1774 \addtoindexx{segment attribute}
1775 containing an empty location description, that
1776 entry is assumed to exist within a 
1777 \addtoindexi{flat}{address space!flat}.
1778 address space.
1779
1780 \textit{Some systems support different classes of 
1781 addresses
1782 \addtoindexx{address class!attribute}. 
1783 The
1784 address class may affect the way a pointer is dereferenced
1785 or the way a subroutine is called.}
1786
1787
1788 Any debugging information entry representing a pointer or
1789 reference type or a subroutine or subroutine type may 
1790 have a 
1791 \DWATaddressclass{}
1792 attribute, whose value is an integer
1793 constant.  The set of permissible values is specific to
1794 each target architecture. The value \DWADDRnoneTARG, 
1795 however,
1796 is common to all encodings, and means that no address class
1797 has been specified.
1798
1799 \textit {For example, the Intel386 \texttrademark\  processor might use the following values:}
1800
1801 \begin{table}[here]
1802 \caption{Example address class codes}
1803 \label{tab:inteladdressclasstable}
1804 \centering
1805 \begin{tabular}{l|c|l}
1806 \hline
1807 Name&Value&Meaning  \\
1808 \hline
1809 \textit{DW\_ADDR\_none}&   0 & \textit{no class specified} \\
1810 \textit{DW\_ADDR\_near16}& 1 & \textit{16\dash bit offset, no segment} \\
1811 \textit{DW\_ADDR\_far16}&  2 & \textit{16\dash bit offset, 16\dash bit segment} \\
1812 \textit{DW\_ADDR\_huge16}& 3 & \textit{16\dash bit offset, 16\dash bit segment} \\
1813 \textit{DW\_ADDR\_near32}& 4 & \textit{32\dash bit offset, no segment} \\
1814 \textit{DW\_ADDR\_far32}&  5 & \textit{32\dash bit offset, 16\dash bit segment} \\
1815 \hline
1816 \end{tabular}
1817 \end{table}
1818
1819 \needlines{6}
1820 \section{Non-Defining Declarations and Completions}
1821 \label{nondefiningdeclarationsandcompletions}
1822 A debugging information entry representing a program entity
1823 typically represents the defining declaration of that
1824 entity. In certain contexts, however, a debugger might need
1825 information about a declaration of an entity that is not
1826 \addtoindexx{incomplete declaration}
1827 also a definition, or is otherwise incomplete, to evaluate
1828 \hypertarget{chap:DWATdeclarationincompletenondefiningorseparateentitydeclaration}
1829 an expression correctly.
1830
1831 \textit{As an example, consider the following fragment of \addtoindex{C} code:}
1832
1833 \begin{lstlisting}
1834 void myfunc()
1835 {
1836   int x;
1837   {
1838     extern float x;
1839     g(x);
1840   }
1841 }
1842 \end{lstlisting}
1843
1844
1845 \textit{\addtoindex{C} scoping rules require that the 
1846 value of the variable x passed to the function g is the value of the
1847 global variable x rather than of the local version.}
1848
1849 \subsection{Non-Defining Declarations}
1850 A debugging information entry that 
1851 represents a non-defining or 
1852 \addtoindex{non-defining declaration}
1853 otherwise 
1854 \addtoindex{incomplete declaration}
1855 of a program entity has 
1856 \addtoindexx{declaration attribute}
1857
1858 \DWATdeclaration{} 
1859 attribute, which is a 
1860 \livelink{chap:classflag}{flag}.
1861
1862 \subsection{Declarations Completing Non-Defining Declarations}
1863 A debugging information entry that represents a 
1864 \hypertarget{chap:DWATspecificationincompletenondefiningorseparatedeclaration}
1865 declaration that completes another (earlier) 
1866 non\dash defining declaration may have a 
1867 \DWATspecification{}
1868 attribute whose value is a \livelink{chap:classreference}{reference} to
1869 the debugging information entry representing the non-defining declaration. A debugging
1870 information entry with a 
1871 \DWATspecification{} 
1872 attribute does not need to duplicate information
1873 provided by the debugging information entry referenced by that specification attribute.
1874
1875 It is not the case that all attributes of the debugging information entry referenced by a
1876 \DWATspecification{} attribute 
1877 apply to the referring debugging information entry.
1878
1879 \textit{For 
1880 \addtoindexx{declaration attribute}
1881 example,
1882 \DWATsibling{} and 
1883 \DWATdeclaration{} 
1884 \addtoindexx{declaration attribute}
1885 clearly cannot apply to a 
1886 \addtoindexx{declaration attribute}
1887 referring
1888 \addtoindexx{sibling attribute}
1889 entry.}
1890
1891
1892
1893 \section{Declaration Coordinates}
1894 \label{chap:declarationcoordinates}
1895 \livetargi{chap:declarationcoordinates}{}{declaration coordinates}
1896 \textit{It is sometimes useful in a debugger to be able to associate
1897 a declaration with its occurrence in the program source.}
1898
1899 Any debugging information 
1900 \hypertarget{chap:DWATdeclfilefilecontainingsourcedeclaration}
1901 entry 
1902 \hypertarget{chap:DWATdecllinelinenumberofsourcedeclaration}
1903 representing 
1904 \hypertarget{chap:DWATdeclcolumncolumnpositionofsourcedeclaration}
1905 the
1906 \addtoindexx{line number of declaration}
1907 declaration of an object, module, subprogram or
1908 \addtoindex{declaration column attribute}
1909 type 
1910 \addtoindex{declaration file attribute}
1911 may 
1912 \addtoindex{declaration line attribute}
1913 have
1914 \DWATdeclfile, 
1915 \DWATdeclline{} and 
1916 \DWATdeclcolumn{}
1917 attributes each of whose value is an unsigned
1918 \livelink{chap:classconstant}{integer constant}.
1919
1920 The value of 
1921 \addtoindexx{declaration file attribute}
1922 the 
1923 \DWATdeclfile{}
1924 attribute 
1925 \addtoindexx{file containing declaration}
1926 corresponds to
1927 a file number from the line number information table for the
1928 compilation unit containing the debugging information entry and
1929 represents the source file in which the declaration appeared
1930 (see Section \refersec{chap:linenumberinformation}). 
1931 The value 0 indicates that no source file
1932 has been specified.
1933
1934 The value of 
1935 \addtoindexx{declaration line attribute}
1936 the \DWATdeclline{} attribute represents
1937 the source line number at which the first character of
1938 the identifier of the declared object appears. The value 0
1939 indicates that no source line has been specified.
1940
1941 The value of 
1942 \addtoindexx{declaration column attribute}
1943 the \DWATdeclcolumn{} attribute represents
1944 the source column number at which the first character of
1945 the identifier of the declared object appears. The value 0
1946 indicates that no column has been specified.
1947
1948 \section{Identifier Names}
1949 \label{chap:identifiernames}
1950 Any 
1951 \hypertarget{chap:DWATnamenameofdeclaration}
1952 debugging information entry 
1953 \addtoindexx{identifier names}
1954 representing 
1955 \addtoindexx{names!identifier}
1956 a program entity
1957 that has been given a name may have a 
1958 \DWATname{} attribute,
1959 whose 
1960 \addtoindexx{name attribute}
1961 value is a \livelink{chap:classstring}{string} 
1962 representing the name as it appears in
1963 the source program. A debugging information entry containing
1964 no name attribute, or containing a name attribute whose value
1965 consists of a name containing a single null byte, represents
1966 a program entity for which no name was given in the source.
1967
1968 \textit{Because the names of program objects described by DWARF are the
1969 names as they appear in the source program, implementations
1970 of language translators that use some form of mangled name
1971 \addtoindex{mangled names}
1972 (as do many implementations of C++) should use the unmangled
1973 form of the name in the 
1974 DWARF \DWATname{} attribute,
1975 \addtoindexx{name attribute}
1976 including the keyword operator (in names such as \doublequote{operator +}),
1977 if present. See also 
1978 Section \refersec{chap:linkagenames} regarding the use
1979 of \DWATlinkagename{} for 
1980 \addtoindex{mangled names}
1981 mangled names. 
1982 Sequences of
1983 multiple whitespace characters may be compressed.}
1984
1985 \section{Data Locations and DWARF Procedures}
1986 Any debugging information entry describing a data object (which
1987 \hypertarget{chap:DWATlocationdataobjectlocation}
1988 includes variables and parameters) or 
1989 \livelink{chap:commonblockentry}{common blocks}
1990 may have 
1991 \addtoindexx{location attribute}
1992 a
1993 \DWATlocation{} attribute,
1994 \addtoindexx{location attribute}
1995 whose value is a location description
1996 (see Section \refersec{chap:locationdescriptions}).
1997
1998
1999 \addtoindex{DWARF procedure}
2000 is represented by any
2001 kind of debugging information entry that has 
2002 \addtoindexx{location attribute}
2003
2004 \DWATlocation{}
2005 attribute. 
2006 \addtoindexx{location attribute}
2007 If a suitable entry is not otherwise available,
2008 a DWARF procedure can be represented using a debugging
2009 \addtoindexx{DWARF procedure entry}
2010 information entry with the 
2011 tag \DWTAGdwarfprocedureTARG{}
2012 together with 
2013 \addtoindexx{location attribute}
2014 a \DWATlocation{} attribute.  
2015
2016 A DWARF procedure
2017 is called by a \DWOPcalltwo, 
2018 \DWOPcallfour{} or 
2019 \DWOPcallref{}
2020 DWARF expression operator 
2021 (see Section \refersec{chap:controlflowoperations}).
2022
2023 \needlines{5}
2024 \section{Code Addresses and Ranges}
2025 \label{chap:codeaddressesandranges}
2026 Any debugging information entry describing an entity that has
2027 a machine code address or range of machine code addresses,
2028 which includes compilation units, module initialization,
2029 \hypertarget{chap:DWATrangesnoncontiguousrangeofcodeaddresses}
2030 subroutines, ordinary \nolink{blocks}, 
2031 try/catch \nolink{blocks} (see Section\refersec{chap:tryandcatchblockentries}), 
2032 labels and the like, may have
2033 \begin{itemize}
2034 \item A \DWATlowpc{} attribute for
2035 \hypertarget{chap:DWATlowpccodeaddressorrangeofaddresses}
2036 a single address,
2037
2038 \item A \DWATlowpc{}
2039 \addtoindexx{low PC attribute}
2040 and 
2041 \DWAThighpc{}
2042 \addtoindexx{high PC attribute}
2043 \hypertarget{chap:DWAThighpccontiguousrangeofcodeaddresses}
2044 pair of attributes for 
2045 a single contiguous range of
2046 addresses, or
2047
2048 \item A \DWATranges{} attribute 
2049 \addtoindexx{ranges attribute}
2050 for a non-contiguous range of addresses.
2051 \end{itemize}
2052
2053 In addition, a non-contiguous range of 
2054 addresses may also be specified for the
2055 \DWATstartscope{} attribute.
2056 \addtoindexx{start scope attribute}
2057
2058 If an entity has no associated machine code, 
2059 none of these attributes are specified.
2060
2061 \subsection{Single Address} 
2062 When there is a single address associated with an entity,
2063 such as a label or alternate entry point of a subprogram,
2064 the entry has a \DWATlowpc{} attribute whose value is the
2065 relocated address for the entity.
2066
2067 \textit{While the \DWATentrypc{}
2068 attribute might also seem appropriate for this purpose,
2069 historically the \DWATlowpc{} attribute was used before the
2070 \DWATentrypc{} was introduced 
2071 (in \addtoindex{DWARF Version 3}). There is
2072 insufficient reason to change this.}
2073
2074 \subsection{Continuous Address Range}
2075 \label{chap:contiguousaddressranges}
2076 When the set of addresses of a debugging information entry can
2077 be described as a single contiguous range, the entry 
2078 \addtoindexx{high PC attribute}
2079 may 
2080 \addtoindexx{low PC attribute}
2081 have
2082 a \DWATlowpc{} and 
2083 \DWAThighpc{} pair of attributes. 
2084 The value
2085 of the 
2086 \DWATlowpc{} attribute 
2087 is the relocated address of the
2088 first instruction associated with the entity. If the value of
2089 the \DWAThighpc{} is of class address, it is the relocated
2090 address of the first location past the last instruction
2091 associated with the entity; if it is of class constant, the
2092 value is an unsigned integer offset which when added to the
2093 low PC gives the address of the first location past the last
2094 instruction associated with the entity.
2095
2096 \textit{The high PC value
2097 may be beyond the last valid instruction in the executable.}
2098
2099 \needlines{5}
2100 The presence of low and high PC attributes for an entity
2101 implies that the code generated for the entity is contiguous
2102 and exists totally within the boundaries specified by those
2103 two attributes. If that is not the case, no low and high PC
2104 attributes should be produced.
2105
2106 \subsection{Non\dash Contiguous Address Ranges}
2107 \label{chap:noncontiguousaddressranges}
2108 When the set of addresses of a debugging information entry
2109 \addtoindexx{non-contiguous address ranges}
2110 cannot be described as a single contiguous range, the entry has
2111 a \DWATranges{} attribute 
2112 \addtoindexx{ranges attribute}
2113 whose value is of class \livelink{chap:classrangelistptr}{rangelistptr}
2114 and indicates the beginning of a \addtoindex{range list}.
2115 Similarly,
2116 a \DWATstartscope{} attribute 
2117 \addtoindexx{start scope attribute}
2118 may have a value of class
2119 \livelink{chap:classrangelistptr}{rangelistptr} for the same reason.  
2120
2121 Range lists are contained
2122 in a separate object file section called 
2123 \dotdebugranges{}. A
2124 \addtoindex{range list} is indicated by a 
2125 \DWATranges{} attribute whose
2126 \addtoindexx{ranges attribute}
2127 value is represented as an offset from the beginning of the
2128 \dotdebugranges{} section to the beginning of the 
2129 \addtoindex{range list}.
2130
2131 Each entry in a \addtoindex{range list} is either a 
2132 \addtoindex{range list} entry,
2133 \addtoindexx{base address selection entry!in range list}
2134 a base address selection entry, or an 
2135 \addtoindexx{end of list entry!in range list}
2136 end of list entry.
2137
2138 A \addtoindex{range list} entry consists of:
2139 \begin{enumerate}[1. ]
2140 \item A beginning address offset. This address offset has the 
2141 \addtoindex{size of an address} and is relative to
2142 the applicable base address of the compilation unit referencing this 
2143 \addtoindex{range list}. 
2144 It marks the
2145 beginning of an 
2146 \addtoindexi{address}{address range!in range list} 
2147 range.
2148
2149 \item An ending address offset. This address offset again has the 
2150 \addtoindex{size of an address} and is relative
2151 to the applicable base address of the compilation unit referencing 
2152 this \addtoindex{range list}.
2153 It marks the
2154 first address past the end of the address range.
2155 The ending address must be greater than or
2156 equal to the beginning address.
2157
2158 \textit{A \addtoindex{range list} entry (but not a base address selection or end of list entry) whose beginning and
2159 ending addresses are equal has no effect because the size of the range covered by such an
2160 entry is zero.}
2161 \end{enumerate}
2162
2163 The applicable base address of a \addtoindex{range list} entry
2164 is determined
2165 by the closest preceding base address selection entry (see
2166 below) in the same range list. If there is no such selection
2167 entry, then the applicable base address defaults to the base
2168 address of the compilation unit 
2169 (see Section \refersec{chap:normalandpartialcompilationunitentries}).
2170
2171 \textit{In the case of a compilation unit where all of the machine
2172 code is contained in a single contiguous section, no base
2173 address selection entry is needed.}
2174
2175 Address range entries in
2176 a \addtoindex{range list} may not overlap.
2177 There is no requirement that
2178 the entries be ordered in any particular way.
2179
2180 \needlines{5}
2181 A base address selection entry consists of:
2182 \begin{enumerate}[1. ]
2183 \item The value of the largest representable address offset (for example, \wffffffff when the size of
2184 an address is 32 bits).
2185
2186 \item An address, which defines the appropriate base address for use in interpreting the beginning
2187 and ending address offsets of subsequent entries of the location list.
2188 \end{enumerate}
2189 \textit{A base address selection entry 
2190 affects only the list in which it is contained.}
2191
2192
2193 The end of any given \addtoindex{range list} is marked by an 
2194 \addtoindexx{end of list entry!in range list}
2195 end of list entry, 
2196 which consists of a 0 for the beginning address
2197 offset and a 0 for the ending address offset. 
2198 A \addtoindex{range list}
2199 containing only an end of list entry describes an empty scope
2200 (which contains no instructions).
2201
2202 \textit{A base address selection entry and an 
2203 \addtoindexx{end of list entry!in range list}
2204 end of list entry for
2205 a \addtoindex{range list} 
2206 are identical to a base address selection entry
2207 and end of list entry, respectively, for a location list
2208 (see Section \refersec{chap:locationlists}) 
2209 in interpretation and representation.}
2210
2211
2212
2213 \section{Entry Address}
2214 \label{chap:entryaddress}
2215 \textit{The entry or first executable instruction generated
2216 for an entity, if applicable, is often the lowest addressed
2217 instruction of a contiguous range of instructions. In other
2218 cases, the entry address needs to be specified explicitly.}
2219
2220 Any debugging information entry describing an entity that has
2221 a range of code addresses, which includes compilation units,
2222 module initialization, subroutines, 
2223 ordinary \livelink{chap:lexicalblock}{block}, 
2224 try/catch \nolink{blocks} (see Section \refersec{chap:tryandcatchblockentries}),
2225 and the like, 
2226 may have a \DWATentrypc{} attribute to
2227 indicate the first executable instruction within that range
2228 of addresses. The value of the \DWATentrypc{} attribute is a
2229 relocated address. If no \DWATentrypc{} attribute is present,
2230 then the entry address is assumed to be the same as the
2231 value of the \DWATlowpc{} attribute, if present; otherwise,
2232 the entry address is unknown.
2233
2234 \section{Static and Dynamic Values of Attributes}
2235 \label{chap:staticanddynamicvaluesofattributes}
2236
2237 Some attributes that apply to types specify a property (such
2238 as the lower bound of an array) that is an integer value,
2239 where the value may be known during compilation or may be
2240 computed dynamically during execution.
2241
2242 The value of these
2243 attributes is determined based on the class as follows:
2244 \begin{itemize}
2245 \item For a \livelink{chap:classconstant}{constant}, the value of the constant is the value of
2246 the attribute.
2247
2248 \item For a \livelink{chap:classreference}{reference}, the
2249 value is a DWARF procedure that computes the value of the attribute.
2250
2251 \item For an \livelink{chap:classexprloc}{exprloc}, the value is interpreted as a 
2252 DWARF expression; 
2253 evaluation of the expression yields the value of
2254 the attribute.
2255 \end{itemize}
2256
2257 \textit{%
2258 Whether an attribute value can be dynamic depends on the
2259 rules of the applicable programming language.
2260 }
2261
2262 \textit{The applicable attributes include: 
2263 \DWATallocated,
2264 \DWATassociated, 
2265 \DWATbitoffset, 
2266 \DWATbitsize,
2267 \DWATbitstride,
2268 \DWATbytesize,
2269 \DWATbytestride, 
2270 \DWATcount, 
2271 \DWATlowerbound,
2272 \DWATrank,
2273 \DWATupperbound,
2274 (and possibly others).}
2275
2276 \needlines{6}
2277 \section{Entity Descriptions}
2278 \textit{Some debugging information entries may describe entities
2279 in the program that are artificial, or which otherwise are
2280 \doublequote{named} in ways which are not valid identifiers in the
2281 programming language. For example, several languages may
2282 capture or freeze the value of a variable at a particular
2283 point in the program. 
2284 \addtoindex{Ada} 95 has package elaboration routines,
2285 type descriptions of the form typename\textquoteright Class, and 
2286 \doublequote{access typename} parameters.  }
2287
2288 Generally, any debugging information
2289 entry that 
2290 \hypertarget{chap:DWATdescriptionartificialnameordescription}
2291 has, or may have, 
2292 \addtoindexx{name attribute}
2293
2294 \DWATname{} attribute, may
2295 also have 
2296 \addtoindexx{description attribute}
2297
2298 \DWATdescription{} attribute whose value is a
2299 null-terminated string providing a description of the entity.
2300
2301
2302 \textit{It is expected that a debugger will only display these
2303 descriptions as part of the description of other entities. It
2304 should not accept them in expressions, nor allow them to be
2305 assigned, or the like.}
2306
2307 \section{Byte and Bit Sizes}
2308 \label{chap:byteandbitsizes}
2309 % Some trouble here with hbox full, so we try optional word breaks.
2310 Many debugging information entries allow either a
2311 \DWATbytesize{} attribute or a 
2312 \DWATbitsize{} attribute,
2313 whose \livelink{chap:classconstant}{integer constant} value 
2314 (see Section \ref{chap:staticanddynamicvaluesofattributes}) 
2315 specifies an
2316 amount of storage. The value of the 
2317 \DWATbytesize{} attribute
2318 is interpreted in bytes and the value of the 
2319 \DWATbitsize{}
2320 attribute is interpreted in bits. The
2321 \DWATstringlengthbytesize{} and 
2322 \DWATstringlengthbitsize{} 
2323 attributes are similar.
2324
2325 In addition, the \livelink{chap:classconstant}{integer constant}
2326 value of a \DWATbytestride{} attribute is interpreted
2327 in bytes and the \livelink{chap:classconstant}{integer constant} value of a 
2328 \DWATbitstride{}
2329 attribute is interpreted in bits.
2330
2331 \section{Linkage Names}
2332 \label{chap:linkagenames}
2333 \textit{Some language implementations, notably 
2334 \addtoindex{C++} and similar
2335 languages, 
2336 make use of implementation-defined names within
2337 object files that are different from the identifier names
2338 (see Section \refersec{chap:identifiernames}) of entities as they appear in the
2339 source. Such names, sometimes known 
2340 \addtoindex{names!mangled}
2341 as 
2342 \addtoindexx{mangled names}
2343 mangled names,
2344 are used in various ways, such as: to encode additional
2345 information about an entity, to distinguish multiple entities
2346 that have the same name, and so on. When an entity has an
2347 associated distinct linkage name it may sometimes be useful
2348 for a producer to include this name in the DWARF description
2349 of the program to facilitate consumer access to and use of
2350 object file information about an entity and/or information
2351 \hypertarget{chap:DWATlinkagenameobjectfilelinkagenameofanentity}
2352 that is encoded in the linkage name itself.  
2353 }
2354
2355 % Some trouble maybe with hbox full, so we try optional word breaks.
2356 A debugging
2357 information entry may have 
2358 \addtoindexx{linkage name attribute}
2359
2360 \DWATlinkagename{}
2361 attribute
2362 whose value is a null-terminated string describing the object
2363 file linkage name associated with the corresponding entity.
2364
2365 % Some trouble here with hbox full, so we try optional word breaks.
2366 \textit{Debugging information entries to which \DWATlinkagename{}
2367 may apply include: \DWTAGcommonblock, \DWTAGconstant,
2368 \DWTAGentrypoint, \DWTAGsubprogram{} 
2369 and \DWTAGvariable.
2370 }