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