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