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