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