Adds index entries for all the index entries in DW4 that
[dwarf-doc.git] / dwarf5 / latexdoc / generaldescription.tex
1 \chapter{General Description}
2 \label{chap:generaldescription}
3 \section{The Debugging Entry (DIE)}
4 \label{chap:thedebuggingentrydie}
5 DWARF uses a series of debugging information entries (DIEs) to 
6 define a low\dash{} level
7 representation of a source program. 
8 Each debugging information entry consists of an identifying
9 tag and a series of attributes. 
10 An entry, or group of entries together, provide a description of a
11 corresponding entity in the source program. 
12 The tag specifies the class to which an entry belongs
13 and the attributes define the specific characteristics of the entry.
14
15 The set of tag names is listed in Figure 1. 
16 The debugging information entries they identify are
17 described in Sections 3, 4 and 5.
18
19 The debugging information entry descriptions 
20 in Sections 3, 4 and 5 generally include mention of
21 most, but not necessarily all, of the attributes 
22 that are normally or possibly used with the entry.
23 Some attributes, whose applicability tends to be 
24 pervasive and invariant across many kinds of
25 debugging information entries, are described in 
26 this section and not necessarily mentioned in all
27 contexts where they may be appropriate. 
28 Examples include \livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial}, the declaration
29 coordinates, and \livelink{chap:DWATdescription}{DW\-\_AT\-\_description}, among others.
30
31 The debugging information entries are contained 
32 in the .debug\_info and .debug\_types
33 sections of an object file.
34
35
36
37 \section{Attribute Types}
38 \label{chap:attributetypes}
39 Each attribute value is characterized by an attribute name. 
40 No more than one attribute with a given name may appear in any
41 debugging information entry. 
42 There are no limitations on the
43 ordering of attributes within a debugging information entry.
44
45 The attributes are listed in Figure 2.  
46
47 The permissible values
48 for an attribute belong to one or more classes of attribute
49 value forms.  
50 Each form class may be represented in one or more ways. 
51 For example, some attribute values consist
52 of a single piece of constant data. 
53 ``Constant data''
54 is the class of attribute value that those attributes may have. 
55 There are several representations of constant data,
56 however (one, two, ,four, or eight bytes, and variable length
57 data). 
58 The particular representation for any given instance
59 of an attribute is encoded along with the attribute name as
60 part of the information that guides the interpretation of a
61 debugging information entry.  
62
63 Attribute value forms belong
64 to one of the classes shown in Figure \refersec{tab:classesofattributevalue}.
65
66 % These each need to link to definition page: FIXME
67 \begin{figure}[here]
68 \autorows[0pt]{c}{2}{l}{
69 \livelink{chap:DWTAGaccessdeclaration}{DW\-\_TAG\-\_access\-\_declaration},
70 \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type},
71 \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type},
72 \livelink{chap:DWTAGcatchblock}{DW\-\_TAG\-\_catch\-\_block},
73 \livelink{chap:DWTAGclasstype}{DW\-\_TAG\-\_class\-\_type},
74 \livelink{chap:DWTAGcommonblock}{DW\-\_TAG\-\_common\-\_block},
75 \livelink{chap:DWTAGcommoninclusion}{DW\-\_TAG\-\_common\-\_inclusion},
76 \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit},
77 \livelink{chap:DWTAGcondition}{DW\-\_TAG\-\_condition},
78 \livelink{chap:DWTAGconsttype}{DW\-\_TAG\-\_const\-\_type},
79 \livelink{chap:DWTAGconstant}{DW\-\_TAG\-\_constant},
80 \livelink{chap:DWTAGdwarfprocedure}{DW\-\_TAG\-\_dwarf\-\_procedure},
81 \livelink{chap:DWTAGentrypoint}{DW\-\_TAG\-\_entry\-\_point},
82 \livelink{chap:DWTAGenumerationtype}{DW\-\_TAG\-\_enumeration\-\_type},
83 \livelink{chap:DWTAGenumerator}{DW\-\_TAG\-\_enumerator},
84 \livelink{chap:DWTAGfiletype}{DW\-\_TAG\-\_file\-\_type},
85 \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter},
86 \livelink{chap:DWTAGfriend}{DW\-\_TAG\-\_friend},
87 \livelink{chap:DWTAGimporteddeclaration}{DW\-\_TAG\-\_imported\-\_declaration},
88 \livelink{chap:DWTAGimportedmodule}{DW\-\_TAG\-\_imported\-\_module},
89 \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit},
90 \livelink{chap:DWTAGinheritance}{DW\-\_TAG\-\_inheritance},
91 \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine},
92 \livelink{chap:DWTAGinterfacetype}{DW\-\_TAG\-\_interface\-\_type},
93 \livelink{chap:DWTAGlabel}{DW\-\_TAG\-\_label},
94 \livelink{chap:DWTAGlexicalblock}{DW\-\_TAG\-\_lexical\-\_block},
95 \livelink{chap:DWTAGmodule}{DW\-\_TAG\-\_module},
96 \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member},
97 \livelink{chap:DWTAGnamelist}{DW\-\_TAG\-\_namelist},
98 \livelink{chap:DWTAGnamelistitem}{DW\-\_TAG\-\_namelist\-\_item},
99 \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace},
100 \livelink{chap:DWTAGpackedtype}{DW\-\_TAG\-\_packed\-\_type},
101 \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit},
102 \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type},
103 \livelink{chap:DWTAGptrtomembertype}{DW\-\_TAG\-\_ptr\-\_to\-\_member\-\_type},
104 \livelink{chap:DWTAGreferencetype}{DW\-\_TAG\-\_reference\-\_type},
105 \livelink{chap:DWTAGrestricttype}{DW\-\_TAG\-\_restrict\-\_type},
106 \livelink{chap:DWTAGrvaluereferencetype}{DW\-\_TAG\-\_rvalue\-\_reference\-\_type},
107 \livelink{chap:DWTAGsettype}{DW\-\_TAG\-\_set\-\_type},
108 \livelink{chap:DWTAGsharedtype}{DW\-\_TAG\-\_shared\-\_type},
109 \livelink{chap:DWTAGstringtype}{DW\-\_TAG\-\_string\-\_type},
110 \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type},
111 \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram},
112 \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type},
113 \livelink{chap:DWTAGsubroutinetype}{DW\-\_TAG\-\_subroutine\-\_type},
114 \livelink{chap:DWTAGtemplatealias}{DW\-\_TAG\-\_template\-\_alias},
115 \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter},
116 \livelink{chap:DWTAGtemplatevalueparameter}{DW\-\_TAG\-\_template\-\_value\-\_parameter},
117 \livelink{chap:DWTAGthrowntype}{DW\-\_TAG\-\_thrown\-\_type},
118 \livelink{chap:DWTAGtryblock}{DW\-\_TAG\-\_try\-\_block},
119 \livelink{chap:DWTAGtypedef}{DW\-\_TAG\-\_typedef},
120 \livelink{chap:DWTAGtypeunit}{DW\-\_TAG\-\_type\-\_unit},
121 \livelink{chap:DWTAGuniontype}{DW\-\_TAG\-\_union\-\_type},
122 \livelink{chap:DWTAGunspecifiedparameters}{DW\-\_TAG\-\_unspecified\-\_parameters},
123 \livelink{chap:DWTAGunspecifiedtype}{DW\-\_TAG\-\_unspecified\-\_type},
124 \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable},
125 \livelink{chap:DWTAGvariant}{DW\-\_TAG\-\_variant},
126 \livelink{chap:DWTAGvariantpart}{DW\-\_TAG\-\_variant\-\_part},
127 \livelink{chap:DWTAGvolatiletype}{DW\-\_TAG\-\_volatile\-\_type},
128 \livelink{chap:DWTAGwithstmt}{DW\-\_TAG\-\_with\-\_stmt},
129 }
130 \caption{Tag names}\label{fig:tagnames}
131 \end{figure}
132
133 \label{tab:attributenames}
134 \setlength{\extrarowheight}{0.1cm}
135 \begin{longtable}{l|p{9cm}}
136   \caption{Attribute names} \\
137   \hline \\ \bfseries Attribute&\bfseries Identifies or Specifies \\ \hline
138 \endfirsthead
139   \bfseries Attribute&\bfseries Identifies or Specifies \\ \hline
140 \endhead
141   \hline \emph{Continued on next page}
142 \endfoot
143   \hline
144 \endlastfoot
145 \livetarg{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
146 &\livelink{chap:DWATabstractorigininlineinstance}{Inline instances of inline subprograms} \\
147 % Heren livelink we cannot use \dash or \dash{}.
148 &\livelink{chap:DWATabstractoriginoutoflineinstance}{Out-of-line instances of inline subprograms} \\
149 \livetarg{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility}
150 &\livelink{chap:DWATaccessibilitycandadadeclarations}{C++ and Ada declarations} \\
151 &\livelink{chap:DWATaccessibilitycppbaseclasses}{C++ base classes} \\
152 &\livelink{chap:DWATaccessibilitycppinheritedmembers}{C++ inherited members} \\
153 \livetarg{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class}
154 &\livelink{chap:DWATadressclasspointerorreferencetypes}{Pointer or reference types} \\
155 &\livelink{chap:DWATaddressclasssubroutineorsubroutinetype}{Subroutine or subroutine type} \\
156 \livetarg{chap:DWATallocated}{DW\-\_AT\-\_allocated}
157 &\livelink{chap:DWATallocatedallocationstatusoftypes}{Allocation status of types} \\
158 \livetarg{chap:DWATartificial}{DW\-\_AT\-\_artificial}
159 &\livelink{chap:DWATartificialobjectsortypesthat}{Objects or types that are not
160 actually declared in the source} \\
161 \livetarg{chap:DWATassociated}{DW\-\_AT\-\_associated} 
162 &\livelink{chap:DWATassociatedassociationstatusoftypes}{Association status of types} \\
163 \livetarg{chap:DWATbasetypes}{DW\-\_AT\-\_base\-\_types} 
164 &\livelink{chap:DWATbasetypesprimitivedatatypesofcompilationunit}{Primitive data types of compilation unit} \\
165 \livetarg{chap:DWATbinaryscale}{DW\-\_AT\-\_binary\-\_scale} 
166 &\livelink{chap:DWATbinaryscalebinaryscalefactorforfixedpointtype}{Binary scale factor for fixed-point type} \\
167 \livetarg{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} 
168 &\livelink{chap:DWATbitoffsetbasetypebitlocation}{Base type bit location} \\
169 &\livelink{chap:DWATbitoffsetdatamemberbitlocation}{Data member bit location} \\
170 \livetarg{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} 
171 &\livelink{chap:DWATbitsizebasetypebitsize}{Base type bit size} \\
172 &\livelink{chap:DWATbitsizedatamemberbitsize}{Data member bit size} \\
173 \livetarg{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride} 
174 &\livelink{chap:DWATbitstridearrayelementstrideofarraytype}{Array element stride (of array type)} \\
175 &\livelink{chap:DWATbitstridesubrangestridedimensionofarraytype}{Subrange stride (dimension of array type)} \\
176 &\livelink{chap:DWATbitstrideenumerationstridedimensionofarraytype}{Enumeration stride (dimension of array type)} \\
177 \livetarg{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} 
178 &\livelink{chap:DWATbytesizedataobjectordatatypesize}{Data object or data type size} \\
179 \livetarg{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride} 
180 &\livelink{chap:DWATbytestridearrayelementstrideofarraytype}{Array element stride (of array type)} \\
181 &\livelink{chap:DWATbytestridesubrangestridedimensionofarraytype}{Subrange stride (dimension of array type)} \\
182 &\livelink{chap:DWATbytestrideenumerationstridedimensionofarraytype}{Enumeration stride (dimension of array type)} \\
183 \livetarg{chap:DWATcallcolumn}{DW\-\_AT\-\_call\-\_column} 
184 &\livelink{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}{Column position of inlined subroutine call}\\
185 \livetarg{chap:DWATcallfile}{DW\-\_AT\-\_call\-\_file}
186 &\livelink{chap:DWATcallfilefilecontaininginlinedsubroutinecall}{File containing inlined subroutine call} \\
187 \livetarg{chap:DWATcallline}{DW\-\_AT\-\_call\-\_line} 
188 &\livelink{chap:DWATcalllinelinenumberofinlinedsubroutinecall}{Line number of inlined subroutine call} \\
189 \livetarg{chap:DWATcallingconvention}{DW\-\_AT\-\_calling\-\_convention} 
190 &\livelink{chap:DWATcallingconventionsubprogramcallingconvention}{Subprogram calling convention} \\
191 \livetarg{chap:DWATcommonreference}{DW\-\_AT\-\_common\-\_reference}
192 &\livelink{chap:commonreferencecommonblockusage}{Common block usage} \\
193 \livetarg{chap:DWATcompdir}{DW\-\_AT\-\_comp\-\_dir}
194 &\livelink{chap:DWATcompdircompilationdirectory}{Compilation directory} \\
195 \livetarg{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}
196 &\livelink{chap:DWATconstvalueconstantobject}{Constant object} \\
197 &\livelink{chap:DWATconstvalueenumerationliteralvalue}{Enumeration literal value} \\
198 &\livelink{chap:DWATconstvaluetemplatevalueparameter}{Template value parameter} \\
199 \livetarg{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr}
200 &\livelink{chap:DWATconstexprcompiletimeconstantobject}{Compile-time constant object} \\
201 &\livelink{chap:DWATconstexprcompiletimeconstantfunction}{Compile-time constant function} \\
202 \livetarg{chap:DWATcontainingtype}{DW\-\_AT\-\_containing\-\_type}
203 &\livelink{chap:DWATcontainingtypecontainingtypeofpointertomembertype}{Containing type of pointer to member type} \\
204 \livetarg{chap:DWATcount}{DW\-\_AT\-\_count}
205 &\livelink{chap:DWATcountelementsofsubrangetype}{Elements of subrange type} \\
206 \livetarg{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}
207 &\livelink{chap:DWATdatabitoffsetbasetypebitlocation}{Base type bit location} \\
208 &\livelink{chap:DWATdatabitoffsetdatamemberbitlocation}{Data member bit location} \\
209 \livetarg{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} 
210 &\livelink{chap:DWATdatalocationindirectiontoactualdata}{Indirection to actual data} \\
211 \livetarg{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location}
212 &\livelink{chap:DWATdatamemberlocationdatamemberlocation}{Data member location} \\
213 &\livelink{chap:DWATdatamemberlocationinheritedmemberlocation}{Inherited member location} \\
214 \livetarg{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale}
215 &\livelink{chap:DWATdecimalscaledecimalscalefactor}{Decimal scale factor} \\
216 \livetarg{chap:DWATdecimalsign}{DW\-\_AT\-\_decimal\-\_sign}
217 &\livelink{chap:DWATdecimalsigndecimalsignrepresentation}{Decimal sign representation} \\
218 \livetarg{chap:DWATdeclcolumn}{DW\-\_AT\-\_decl\-\_column}
219 &\livelink{chap:DWATdeclcolumncolumnpositionofsourcedeclaration}{Column position of source declaration} \\
220 \livetarg{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file}
221 &\livelink{chap:DWATdeclfilefilecontainingsourcedeclaration}{File containing source declaration} \\
222 \livetarg{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line}
223 &\livelink{chap:DWATdecllinelinenumberofsourcedeclaration}{Line number of source declaration} \\
224 \livetarg{chap:DWATdeclaration}{DW\-\_AT\-\_declaration}
225 &\livelink{chap:DWATdeclarationincompletenondefiningorseparateentitydeclaration}{Incomplete, non-defining, or separate entity declaration} \\
226 \livetarg{chap:DWATdefaultvalue}{DW\-\_AT\-\_default\-\_value}
227 &\livelink{chap:DWATdefaultvaluedefaultvalueofparameter}{Default value of parameter} \\
228 \livetarg{chap:DWATdescription}{DW\-\_AT\-\_description} 
229 &\livelink{chap:DWATdescriptionartificialnameordescription}{Artificial name or description} \\
230 \livetarg{chap:DWATdigitcount}{DW\-\_AT\-\_digit\-\_count}
231 &\livelink{chap:DWATdigitcountdigitcountforpackeddecimalornumericstringtype}{Digit count for packed decimal or numeric string type} \\
232 \livetarg{chap:DWATdiscr}{DW\-\_AT\-\_discr}
233 &\livelink{chap:DWATdiscrdiscriminantofvariantpart}{Discriminant of variant part} \\
234 \livetarg{chap:DWATdiscrlist}{DW\-\_AT\-\_discr\-\_list}
235 &\livelink{chap:DWATdiscrlistlistofdiscriminantvalues}{List of discriminant values} \\
236 \livetarg{chap:DWATdiscrvalue}{DW\-\_AT\-\_discr\-\_value}
237 &\livelink{chap:DWATdiscrvaluediscriminantvalue}{Discriminant value} \\
238 \livetarg{chap:DWATelemental}{DW\-\_AT\-\_elemental}
239 &\livelink{chap:DWATelementalelementalpropertyofasubroutine}{Elemental property of a subroutine} \\
240 \livetarg{chap:DWATencoding}{DW\-\_AT\-\_encoding}
241 &\livelink{chap:DWATencodingencodingofbasetype}{Encoding of base type} \\
242 \livetarg{chap:DWATendianity}{DW\-\_AT\-\_endianity}
243 &\livelink{chap:DWATendianityendianityofdata}{Endianity of data} \\
244 \livetarg{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc}
245 &\livelink{chap:DWATentrypcentryaddressofmoduleinitialization}{Entry address of module initialization}\\
246 &\livelink{chap:DWATentrypcentryaddressofsubprogram}{Entry address of subprogram} \\
247 &\livelink{chap:DWATentrypcentryaddressofinlinedsubprogram}{Entry address of inlined subprogram}\\
248 \livetarg{chap:DWATenumclass}{DW\-\_AT\-\_enum\-\_class}
249 &\livelink{chap:DWATenumclasstypesafeenumerationdefinition}{Type safe enumeration definition}\\
250 \livetarg{chap:DWATexplicit}{DW\-\_AT\-\_explicit}
251 &\livelink{chap:DWATexplicitexplicitpropertyofmemberfunction}{Explicit property of member function}\\
252 \livetarg{chap:DWATextension}{DW\-\_AT\-\_extension}
253 &\livelink{chap:DWATextensionpreviousnamespaceextensionororiginalnamespace}{Previous namespace extension or original namespace}\\
254 \livetarg{chap:DWATexternal}{DW\-\_AT\-\_external}
255 &\livelink{chap:DWATexternalexternalsubroutine}{External subroutine} \\
256 &\livelink{chap:DWATexternalexternalvariable}{External variable} \\
257 \livetarg{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base}
258 &\livelink{chap:DWATframebasesubroutineframebaseaddress}{Subroutine frame base address} \\
259 \livetarg{chap:DWATfriend}{DW\-\_AT\-\_friend}
260 &\livelink{chap:DWATfriendfriendrelationship}{Friend relationship} \\
261 \livetarg{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}
262 &\livelink{chap:DWAThighpccontinguousrangeofcodeaddresses}{Contiguous range of code addresses} \\
263 \livetarg{chap:DWATidentifiercase}{DW\-\_AT\-\_identifier\-\_case}
264 &\livelink{chap:DWATidentifiercaseidentifiercaserule}{Identifier case rule} \\
265 \livetarg{chap:DWATimport}{DW\-\_AT\-\_import}
266 &\livelink{chap:DWATimportimporteddeclaration}{Imported declaration} \\
267 &\livelink{chap:DWATimportimportedunit}{Imported unit} \\
268 &\livelink{chap:DWATimportnamespacealias}{Namespace alias} \\
269 &\livelink{chap:DWATimportnamespaceusingdeclaration}{Namespace using declaration} \\
270 &\livelink{chap:DWATimportnamespaceusingdirective}{Namespace using directive} \\
271 \livetarg{chap:DWATinline}{DW\-\_AT\-\_inline}
272 &\livelink{chap:DWATinlineabstracttinstance}{Abstract instance} \\
273 &\livelink{chap:DWATinlineinlinedsubroutine}{Inlined subroutine} \\
274 \livetarg{chap:DWATisoptional}{DW\-\_AT\-\_is\-\_optional}
275 &\livelink{chap:DWATisoptionaloptionalparameter}{Optional parameter} \\
276 \livetarg{chap:DWATlanguage}{DW\-\_AT\-\_language}
277 &\livelink{chap:DWATlanguageprogramminglanguage}{Programming language} \\
278 \livetarg{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name}
279 &\livelink{chap:DWATlinkagenameobjectfilelinkagenameofanentity}{Object file linkage name of an entity}\\
280 \livetarg{chap:DWATlocation}{DW\-\_AT\-\_location}
281 &\livelink{chap:DWATlocationdataobjectlocation}{Data object location}\\
282 \livetarg{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}
283 &\livelink{chap:DWATlowpccodeaddressorrangeofaddresses}{Code address or range of addresses}\\
284 \livetarg{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}
285 &\livelink{chap:DWATlowerboundlowerboundofsubrange}{Lower bound of subrange} \\
286 \livetarg{chap:DWATmacroinfo}{DW\-\_AT\-\_macro\-\_info}
287 &\livelink{chap:DWATmacroinfomacroinformation}{Macro information} (\#define, \#undef)\\
288 \livetarg{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram}
289 &\livelink{chap:DWATmainsubprogrammainorstartingsubprogram}{Main or starting subprogram} \\
290 &\livelink{chap:DWATmainsubprogramunitcontainingmainorstartingsubprogram}{Unit containing main or starting subprogram}\\
291 \livetarg{chap:DWATmutable}{DW\-\_AT\-\_mutable}
292 &\livelink{chap:DWATmutablemutablepropertyofmemberdata}{Mutable property of member data} \\
293 \livetarg{chap:DWATname}{DW\-\_AT\-\_name}
294 &\livelink{chap:DWATnamenameofdeclaration}{Name of declaration}\\
295 &\livelink{chap:DWATnamepathnameofcompilationsource}{Path name of compilation source} \\
296 \livetarg{chap:DWATnamelistitem}{DW\-\_AT\-\_namelist\-\_item}
297 &\livelink{chap:DWATnamelistitemnamelistitem}{Namelist item}\\
298 \livetarg{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer}
299 &\livelink{chap:DWATobjectpointerobjectthisselfpointerofmemberfunction}{Object (this, self) pointer of member function}\\
300 \livetarg{chap:DWATordering}{DW\-\_AT\-\_ordering}
301 &\livelink{chap:DWATorderingarrayrowcolumnordering}{Array row/column ordering} \\
302 \livetarg{chap:DWATpicturestring}{DW\-\_AT\-\_picture\-\_string}
303 &\livelink{chap:DWATpicturestringpicturestringfornumericstringtype}{Picture string for numeric string type} \\
304 \livetarg{chap:DWATpriority}{DW\-\_AT\-\_priority}
305 &\livelink{chap:DWATprioritymodulepriority}{Module priority}\\
306 \livetarg{chap:DWATproducer}{DW\-\_AT\-\_producer}
307 &\livelink{chap:DWATproducercompileridentification}{Compiler identification}\\
308 \livetarg{chap:DWATprototyped}{DW\-\_AT\-\_prototyped}
309 &\livelink{chap:DWATprototypedsubroutineprototype}{Subroutine prototype}\\
310 \livetarg{chap:DWATpure}{DW\-\_AT\-\_pure}
311 &\livelink{chap:DWATpurepurepropertyofasubroutine}{Pure property of a subroutine} \\
312 \livetarg{chap:DWATranges}{DW\-\_AT\-\_ranges}
313 &\livelink{chap:DWATrangesnoncontiguousrangeofcodeaddresses}{Non-contiguous range of code addresses} \\
314 \livetarg{chap:DWATrecursive}{DW\-\_AT\-\_recursive}
315 &\livelink{chap:DWATrecursiverecursivepropertyofasubroutine}{Recursive property of a subroutine} \\
316 \livetarg{chap:DWATreturnaddr}{DW\-\_AT\-\_return\-\_addr}
317 &\livelink{chap:DWATreturnaddrsubroutinereturnaddresssavelocation}{Subroutine return address save location} \\
318 \livetarg{chap:DWATsegment}{DW\-\_AT\-\_segment}
319 &\livelink{chap:DWATsegmentaddressinginformation}{Addressing information} \\
320 \livetarg{chap:DWATsibling}{DW\-\_AT\-\_sibling}
321 &\livelink{chap:DWATsiblingdebugginginformationentryrelationship}{Debugging information entry relationship} \\
322 \livetarg{chap:DWATsmall}{DW\-\_AT\-\_small}
323 &\livelink{chap:DWATsmallscalefactorforfixedpointtype}{Scale factor for fixed-point type} \\
324 \livetarg{chap:DWATsignature}{DW\-\_AT\-\_signature}
325 &\livelink{chap:DWATsignaturetypesignature}{Type signature}\\
326 \livetarg{chap:DWATspecification}{DW\-\_AT\-\_specification}
327 &\livelink{chap:DWATspecificationincompletenondefiningorseparatedeclaration}{Incomplete, non-defining, or separate declaration corresponding to a declaration } \\
328 \livetarg{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope}
329 &\livelink{chap:DWATstartscopeobjectdeclaration}{Object declaration}\\
330 &\livelink{chap:DWATstartscopetypedeclaration}{Type declaration}\\
331 \livetarg{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link}
332 &\livelink{chap:DWATstaticlinklocationofuplevelframe}{Location of uplevel frame} \\
333 \livetarg{chap:DWATstmtlist}{DW\-\_AT\-\_stmt\-\_list}
334 &\livelink{chap:DWATstmtlistlinenumberinformationforunit}{Line number information for unit}\\
335 \livetarg{chap:DWATstringlength}{DW\-\_AT\-\_string\-\_length}
336 &\livelink{chap:DWATstringlengthstringlengthofstringtype}{String length of string type} \\
337 \livetarg{chap:DWATthreadsscaled}{DW\-\_AT\-\_threads\-\_scaled}
338 &\livelink{chap:DWATthreadsscaledupcarrayboundthreadsscalfactor}{UPC array bound THREADS scale factor}\\
339 \livetarg{chap:DWATtrampoline}{DW\-\_AT\-\_trampoline}
340 &\livelink{chap:DWATtrampolinetargetsubroutine}{Target subroutine} \\
341 \livetarg{chap:DWATtype}{DW\-\_AT\-\_type}
342 &\livelink{chap:DWATtypetypeofdeclaration}{Type of declaration} \\
343 &\livelink{chap:DWATtypetypeofsubroutinereturn}{Type of subroutine return} \\
344 \livetarg{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}
345 &\livelink{chap:DWATupperboundupperboundofsubrange}{Upper bound of subrange} \\
346 \livetarg{chap:DWATuselocation}{DW\-\_AT\-\_use\-\_location}
347 &\livelink{chap:DWATuselocationmemberlocationforpointertomembertype}{Member location for pointer to member type} \\
348 \livetarg{chap:DWATuseUTF8}{DW\-\_AT\-\_use\-\_UTF8}
349 &\livelink{chap:DWATuseUTF8compilationunitusesutf8strings}{Compilation unit uses UTF-8 strings} \\
350 \livetarg{chap:DWATvariableparameter}{DW\-\_AT\-\_variable\-\_parameter}
351 &\livelink{chap:DWATvariableparameternonconstantparameterflag}{Non-constant parameter flag}  \\
352 \livetarg{chap:DWATvirtuality}{DW\-\_AT\-\_virtuality}
353 &\livelink{chap:DWATvirtualityvirtualityindication}{Virtuality indication} \\
354 &\livelink{chap:DWATvirtualityvirtualityofbaseclass}{Virtuality of base class} \\
355 &\livelink{chap:DWATvirtualityvirtualityoffunction}{Virtuality of function} \\
356 \livetarg{chap:DWATvisibility}{DW\-\_AT\-\_visibility}
357 &\livelink{chap:DWATvisibilityvisibilityofdeclaration}{Visibility of declaration} \\
358 \livetarg{chap:DWATvtableelemlocation}{DW\-\_AT\-\_vtable\-\_elem\-\_location}
359 &\livelink{chap:DWATvtableelemlocationvirtualfunctiontablevtableslot}{Virtual function vtable slot}\\
360 \end{longtable}
361
362 \begin{figure}[here]
363 \centering
364 % Attribute Class entries need a ref to definition point.
365 \setlength{\extrarowheight}{0.1cm}
366 \label{tab:classesofattributevalue}
367 \begin{tabular}{l|p{10cm}} \hline
368 Attribute Class & General Use and Encoding \\ \hline
369 \livetargi{chap:address}{address}{address class}
370 &Refers to some location in the address space of the described program.
371  \\ 
372 \livetargi{chap:block}{block}{block class}
373 & An arbitrary number of uninterpreted bytes of data.
374  \\
375 \livetargi{chap:constant}{constant}{constant class}
376 &One, two, four or eight bytes of uninterpreted data, or data
377 encoded in the variable length format known as LEB128 (see
378 Section 7.6.).
379
380 \textit{Most constant values are integers of one kind or
381 another (codes, offsets, counts, and so on); these are
382 sometimes called ``integer constants'' for emphasis.} \\
383
384 \livetargi{chap:exprloc}{exprloc}{exprloc class}
385 &A DWARF expression or location description.
386 \\
387 \livetargi{chap:flag}{flag}{flag class}
388 &A small constant that indicates the presence or absence of an attribute.
389 \\
390 \livetargi{chap:lineptr}{lineptr}{lineptr class}
391 &Refers to a location in the DWARF section that holds line number information.
392 \\
393 \livetargi{chap:loclistptr}{loclistptr}{loclistptr class}
394 &Refers to a location in the DWARF section that holds location lists, which
395 describe objects whose location can change during their lifetime.
396 \\
397 \livetargi{chap:macptr}{macptr}{macptr class}
398 & Refers to a location in the DWARF section that holds macro definition
399  information.  \\
400 \livetargi{chap:rangelistptr}{rangelistptr}{rangelistptr class}
401 & Refers to a location in the DWARF section that holds non\dash contiguous address ranges.  \\
402
403 \livetargi{chap:reference}{reference}{reference class}
404 & Refers to one of the debugging information
405 entries that describe the program.  There are three types of
406 reference. The first is an offset relative to the beginning
407 of the compilation unit in which the reference occurs and must
408 refer to an entry within that same compilation unit. The second
409 type of reference is the offset of a debugging information
410 entry in any compilation unit, including one different from
411 the unit containing the reference. The third type of reference
412 is an indirect reference to a type definition using a 64\dash
413 bit signature for that type.  \\
414
415 \livetargi{chap:string}{string}{string class}
416 & A null\dash terminated sequence of zero or more
417 (non\dash null) bytes. Data in this class are generally
418 printable strings. Strings may be represented directly in
419 the debugging information entry or as an offset in a separate
420 string table.  
421 \end{tabular}
422 \caption{Classes of Attribute value}
423 \end{figure}
424 % It is difficult to get the above table to appear before
425 % the end of the chapter without a clearpage here.
426 \clearpage
427 \section{Relationship of Debugging Information Entries}
428 \label{chap:relationshipofdebugginginformationentries}
429 \textit{
430 A variety of needs can be met by permitting a single
431 debugging information entry to “own” an arbitrary number
432 of other debugging entries and by permitting the same debugging
433 information entry to be one of many owned by another debugging
434 information entry. 
435 This makes it possible, for example, to
436 describe the static \livelink{chap:lexicalblock}{block} structure 
437 within a source file,
438 to show the members of a structure, union, or class, and to
439 associate declarations with source files or source files
440 with shared objects.  
441 }
442
443
444 The ownership relation of debugging
445 information entries is achieved naturally because the debugging
446 information is represented as a tree. 
447 The nodes of the tree
448 are the debugging information entries themselves. 
449 The child
450 entries of any node are exactly those debugging information
451 entries owned by that node.  
452
453 \textit{
454 While the ownership relation
455 of the debugging information entries is represented as a
456 tree, other relations among the entries exist, for example,
457 a reference from an entry representing a variable to another
458 entry representing the type of that variable. 
459 If all such
460 relations are taken into account, the debugging entries
461 form a graph, not a tree.  
462 }
463
464 The tree itself is represented
465 by flattening it in prefix order. 
466 Each debugging information
467 entry is defined either to have child entries or not to have
468 child entries (see Section 7.5.3). 
469 If an entry is defined not
470 to have children, the next physically succeeding entry is a
471 sibling. 
472 If an entry is defined to have children, the next
473 physically succeeding entry is its first child. 
474 Additional
475 children are represented as siblings of the first child. 
476 A chain of sibling entries is terminated by a null entry.
477
478 In cases where a producer of debugging information feels that
479 \hypertarget{chap:DWATsiblingdebugginginformationentryrelationship}
480 it will be important for consumers of that information to
481 quickly scan chains of sibling entries, while ignoring the
482 children of individual siblings, that producer may attach a
483 \livelink{chap:DWATsibling}{DW\-\_AT\-\_sibling} attribute to any debugging information entry. 
484 The
485 value of this attribute is a reference to the sibling entry
486 of the entry to which the attribute is attached.
487
488
489 \section{Target Addresses}
490 \label{chap:targetaddresses}
491 Many places in this document 
492 refer
493 \addtoindexx{address size|see{size of an address}}
494 to the size 
495 \addtoindexx{address!size of an|see{size of an address}}
496 of an
497 \addtoindexi{address}{size of an address}
498 on the target architecture (or equivalently, target machine)
499 to which a DWARF description applies. For processors which
500 can be configured to have different address sizes or different
501 instruction sets, the intent is to refer to the configuration
502 which is either the default for that processor or which is
503 specified by the object file or executable file which contains
504 the DWARF information.
505
506
507
508 \textit{
509 For example, if a particular target architecture supports
510 both 32\dash bit and 64\dash bit addresses, the compiler will generate
511 an object file which specifies that it contains executable
512 code generated for one or the other of these address sizes. In
513 that case, the DWARF debugging information contained in this
514 object file will use the same address size.
515 }
516
517 \textit{
518 Architectures which have multiple instruction sets are
519 supported by the isa entry in the line number information
520 (see Section \refersec{chap:statemachineregisters}).
521 }
522
523
524 \section{DWARF Expressions}
525 \label{chap:dwarfexpressions}
526 DWARF expressions describe how to compute a value or name a
527 location during debugging of a program. 
528 They are expressed in
529 terms of DWARF operations that operate on a stack of values.
530
531 All DWARF operations are encoded as a stream of opcodes that
532 are each followed by zero or more literal operands. 
533 The number
534 of operands is determined by the opcode.  
535
536 In addition to the
537 general operations that are defined here, operations that are
538 specific to location descriptions are defined in 
539 Section \refersec{chap:locationdescriptions} .
540
541 \subsection{General Operations}
542 \label{chap:generaloperations}
543 Each general operation represents a postfix operation on
544 a simple stack machine. Each element of the stack is the
545 size of an address on the target machine. The value on the
546 top of the stack after ``executing'' the DWARF expression
547 is taken to be the result (the address of the object, the
548 value of the array bound, the length of a dynamic string,
549 the desired value itself, and so on).
550
551 \subsubsection{Literal Encodings}
552 \label{chap:literalencodings}
553 The following operations all push a value onto the DWARF
554 stack. If the value of a constant in one of these operations
555 is larger than can be stored in a single stack element, the
556 value is truncated to the element size and the low\dash order bits
557 are pushed on the stack.
558
559 \begin{enumerate}[1]
560 \item \livetarg{chap:DWOPlit0}{DW\-\_OP\-\_lit0}, \livetarg{chap:DWOPlit1}{DW\-\_OP\-\_lit1}, \dots, \livetarg{chap:DWOPlit31}{DW\-\_OP\-\_lit31} \\
561 The \livetarg{chap:DWOPlit}{DW\-\_OP\-\_lit}n operations encode the unsigned literal values
562 from 0 through 31, inclusive.
563
564 \item \livetarg{chap:DWOPaddr}{DW\-\_OP\-\_addr} \\
565 The \livelink{chap:DWOPaddr}{DW\-\_OP\-\_addr} operation has a single operand that encodes
566 a machine address and whose size is the size of an address
567 on the target machine.
568
569 \item \livetarg{chap:DWOPconst1u}{DW\-\_OP\-\_const1u}, \livetarg{chap:DWOPconst2u}{DW\-\_OP\-\_const2u}, \livetarg{chap:DWOPconst4u}{DW\-\_OP\-\_const4u}, \livetarg{chap:DWOPconst8u}{DW\-\_OP\-\_const8u} \\
570 The single operand of a \livetarg{chap:DWOPconstnu}{DW\-\_OP\-\_constnu} operation provides a 1,
571 2, 4, or 8\dash byte unsigned integer constant, respectively.
572
573 \item \livetarg{chap:DWOPconst1s}{DW\-\_OP\-\_const1s} , \livetarg{chap:DWOPconst2s}{DW\-\_OP\-\_const2s}, \livetarg{chap:DWOPconst4s}{DW\-\_OP\-\_const4s}, \livetarg{chap:DWOPconst8s}{DW\-\_OP\-\_const8s} \\
574 The single operand of a \livetarg{chap:DWOPconstns}{DW\-\_OP\-\_constns} operation provides a 1,
575 2, 4, or 8\dash byte signed integer constant, respectively.
576
577 \item \livetarg{chap:DWOPconstu}{DW\-\_OP\-\_constu} \\
578 The single operand of the \livelink{chap:DWOPconstu}{DW\-\_OP\-\_constu} operation provides
579 an unsigned LEB128 integer constant.
580
581 \item \livetarg{chap:DWOPconsts}{DW\-\_OP\-\_consts} \\
582 The single operand of the \livelink{chap:DWOPconsts}{DW\-\_OP\-\_consts} operation provides
583 a signed LEB128 integer constant.
584
585 \end{enumerate}
586
587
588 \subsubsection{Register Based Addressing}
589 \label{chap:registerbasedaddressing}
590 The following operations push a value onto the stack that is
591 the result of adding the contents of a register to a given
592 signed offset.
593
594 \begin{enumerate}[1]
595
596 \item \livetarg{chap:DWOPfbreg}{DW\-\_OP\-\_fbreg} \\
597 The \livelink{chap:DWOPfbreg}{DW\-\_OP\-\_fbreg} operation provides a signed LEB128 offset
598 from the address specified by the location description in the
599 \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attribute of the current function. (This
600 is typically a “stack pointer” register plus or minus
601 some offset. On more sophisticated systems it might be a
602 location list that adjusts the offset according to changes
603 in the stack pointer as the PC changes.)
604
605 \item \livetarg{chap:DWOPbreg0}{DW\-\_OP\-\_breg0}, \livetarg{chap:DWOPbreg1}{DW\-\_OP\-\_breg1}, \dots, \livetarg{chap:DWOPbreg31}{DW\-\_OP\-\_breg31} \\
606 The single operand of the \livetarg{chap:DWOPbreg}{DW\-\_OP\-\_breg}n 
607 operations provides
608 a signed LEB128 offset from
609 the specified register.
610
611 \item \livetarg{chap:DWOPbregx}{DW\-\_OP\-\_bregx} \\
612 The \livelink{chap:DWOPbregx}{DW\-\_OP\-\_bregx} operation has two operands: a register
613 which is specified by an unsigned LEB128 number, followed by
614 a signed LEB128 offset.
615
616 \end{enumerate}
617
618
619 \subsubsection{Stack Operations}
620 \label{chap:stackoperations}
621 The following operations manipulate the DWARF stack. Operations
622 that index the stack assume that the top of the stack (most
623 recently added entry) has index 0.
624
625 \begin{enumerate}[1]
626 \item \livetarg{chap:DWOPdup}{DW\-\_OP\-\_dup} \\
627 The \livelink{chap:DWOPdup}{DW\-\_OP\-\_dup} operation duplicates the value at the top of the stack.
628
629 \item \livetarg{chap:DWOPdrop}{DW\-\_OP\-\_drop} \\
630 The \livelink{chap:DWOPdrop}{DW\-\_OP\-\_drop} operation pops the value at the top of the stack.
631
632 \item \livetarg{chap:DWOPpick}{DW\-\_OP\-\_pick} \\
633 The single operand of the \livelink{chap:DWOPpick}{DW\-\_OP\-\_pick} operation provides a
634 1\dash byte index. A copy of the stack entry with the specified
635 index (0 through 255, inclusive) is pushed onto the stack.
636
637 \item \livetarg{chap:DWOPover}{DW\-\_OP\-\_over} \\
638 The \livelink{chap:DWOPover}{DW\-\_OP\-\_over} operation duplicates the entry currently second
639 in the stack at the top of the stack. 
640 This is equivalent to
641 a \livelink{chap:DWOPpick}{DW\-\_OP\-\_pick} operation, with index 1.  
642
643 \item \livetarg{chap:DWOPswap}{DW\-\_OP\-\_swap} \\
644 The \livelink{chap:DWOPswap}{DW\-\_OP\-\_swap} operation swaps the top two stack entries. 
645 The entry at the top of the
646 stack becomes the second stack entry, 
647 and the second entry becomes the top of the stack.
648
649 \item \livetarg{chap:DWOProt}{DW\-\_OP\-\_rot} \\
650 The \livelink{chap:DWOProt}{DW\-\_OP\-\_rot} operation rotates the first three stack
651 entries. The entry at the top of the stack becomes the third
652 stack entry, the second entry becomes the top of the stack,
653 and the third entry becomes the second entry.
654
655 \item  \livetarg{chap:DWOPderef}{DW\-\_OP\-\_deref} \\
656 The 
657 \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref} 
658 operation 
659 pops the top stack entry and 
660 treats it as an address. The value
661 retrieved from that address is pushed. 
662 The size of the data retrieved from the 
663 \addtoindexi{dereferenced}{address!dereference operator}
664 address is the size of an address on the target machine.
665
666 \item \livetarg{chap:DWOPderefsize}{DW\-\_OP\-\_deref\-\_size} \\
667 The \livelink{chap:DWOPderefsize}{DW\-\_OP\-\_deref\-\_size} operation behaves like the \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref}
668 operation: it pops the top stack entry and treats it as an
669 address. The value retrieved from that address is pushed. In
670 the \livelink{chap:DWOPderefsize}{DW\-\_OP\-\_deref\-\_size} operation, however, the size in bytes
671 of the data retrieved from the dereferenced address is
672 specified by the single operand. This operand is a 1\dash byte
673 unsigned integral constant whose value may not be larger
674 than the size of an address on the target machine. The data
675 retrieved is zero extended to the size of an address on the
676 target machine before being pushed onto the expression stack.
677
678 \item \livetarg{chap:DWOPxderef}{DW\-\_OP\-\_xderef} \\
679 The \livelink{chap:DWOPxderef}{DW\-\_OP\-\_xderef} operation provides an extended dereference
680 mechanism. The entry at the top of the stack is treated as an
681 address. The second stack entry is treated as an ``address
682 space identifier'' for those architectures that support
683 \addtoindexi{multiple}{address space!multiple}
684 address spaces. The top two stack elements are popped,
685 and a data item is retrieved through an implementation\dash defined
686 address calculation and pushed as the new stack top. The size
687 of the data retrieved from the 
688 \addtoindexi{dereferenced}{address!dereference operator}
689 address is the
690 size of an address on the target machine.
691
692 \item \livetarg{chap:DWOPxderefsize}{DW\-\_OP\-\_xderef\-\_size}\\
693 The \livelink{chap:DWOPxderefsize}{DW\-\_OP\-\_xderef\-\_size} operation behaves like the
694 \livelink{chap:DWOPxderef}{DW\-\_OP\-\_xderef} operation.The entry at the top of the stack is
695 treated as an address. The second stack entry is treated as
696 an ``address space identifier'' for those architectures
697 that support 
698 \addtoindexi{multiple}{address space!multiple}
699 address spaces. The top two stack
700 elements are popped, and a data item is retrieved through an
701 implementation\dash defined address calculation and pushed as the
702 new stack top. In the \livelink{chap:DWOPxderefsize}{DW\-\_OP\-\_xderef\-\_size} operation, however,
703 the size in bytes of the data retrieved from the 
704 \addtoindexi{dereferenced}{address!dereference operator}
705 address is specified by the single operand. This operand is a
706 1\dash byte unsigned integral constant whose value may not be larger
707 than the size of an address on the target machine. The data
708 retrieved is zero extended to the size of an address on the
709 target machine before being pushed onto the expression stack.
710
711 \item \livetarg{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}\\
712 The \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address} operation pushes the address
713 of the object currently being evaluated as part of evaluation
714 of a user presented expression. This object may correspond
715 to an independent variable described by its own debugging
716 information entry or it may be a component of an array,
717 structure, or class whose address has been dynamically
718 determined by an earlier step during user expression
719 evaluation.  This operator provides explicit functionality
720 (especially for arrays involving descriptors) that is analogous
721 to the implicit push of the base 
722 \addtoindexi{address}{address!implicit push of base}
723 of a structure prior
724 to evaluation of a \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} to access a
725 data member of a structure. For an example, see 
726 Appendix \refersec{app:aggregateexamples}.
727
728 \item \livetarg{chap:DWOPformtlsaddress}{DW\-\_OP\-\_form\-\_tls\-\_address} \\
729 The \livelink{chap:DWOPformtlsaddress}{DW\-\_OP\-\_form\-\_tls\-\_address} operation pops a value from the
730 stack, translates it into an address in the current thread's
731 thread\dash local storage \nolink{block}, and pushes the address. If the
732 DWARF expression containing 
733 the \livelink{chap:DWOPformtlsaddress}{DW\-\_OP\-\_form\-\_tls\-\_address}
734 operation belongs to the main executable's DWARF info, the
735 operation uses the main executable's thread\dash local storage
736 \nolink{block}; if the expression belongs to a shared library's
737 DWARF info, then it uses that shared library's thread\dash local
738 storage \nolink{block}.  Some implementations of C and C++ support a
739 \_\_thread storage class. Variables with this storage class
740 have distinct values and addresses in distinct threads, much
741 as automatic variables have distinct values and addresses in
742 each function invocation. Typically, there is a single \nolink{block}
743 of storage containing all \_\_thread variables declared in
744 the main executable, and a separate \nolink{block} for the variables
745 declared in each shared library. Computing the address of
746 the appropriate \nolink{block} can be complex (in some cases, the
747 compiler emits a function call to do it), and difficult
748 to describe using ordinary DWARF location descriptions.
749 \livelink{chap:DWOPformtlsaddress}{DW\-\_OP\-\_form\-\_tls\-\_address} leaves the computation to the
750 consumer.
751
752 \item \livetarg{chap:DWOPcallframecfa}{DW\-\_OP\-\_call\-\_frame\-\_cfa} \\
753 The \livelink{chap:DWOPcallframecfa}{DW\-\_OP\-\_call\-\_frame\-\_cfa} operation pushes the value of the
754 CFA, obtained from the Call Frame Information 
755 (see Section \refersec{chap:callframeinformation}).
756 Although the value of \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base}
757 can be computed using other DWARF expression operators,
758 in some cases this would require an extensive location list
759 because the values of the registers used in computing the
760 CFA change during a subroutine. If the 
761 Call Frame Information 
762 is present, then it already encodes such changes, and it is
763 space efficient to reference that.
764 \end{enumerate}
765
766 \subsubsection{Arithmetic and Logical Operations}
767 The following provide arithmetic and logical operations. Except
768 as otherwise specified, the arithmetic operations perfom
769 addressing arithmetic, that is, unsigned arithmetic that is
770 performed modulo one plus the largest representable address
771 (for example, 0x100000000 when the size of an address is 32
772 bits). Such operations do not cause an exception on overflow.
773
774 \begin{enumerate}[1]
775 \item \livetarg{chap:DWOPabs}{DW\-\_OP\-\_abs}  \\
776 The \livelink{chap:DWOPabs}{DW\-\_OP\-\_abs} operation pops the top stack entry, interprets
777 it as a signed value and pushes its absolute value. If the
778 absolute value cannot be represented, the result is undefined.
779
780 \item \livetarg{chap:DWOPand}{DW\-\_OP\-\_and} \\
781 The \livelink{chap:DWOPand}{DW\-\_OP\-\_and} operation pops the top two stack values, performs
782 a bitwise and operation on the two, and pushes the result.
783
784 \item \livetarg{chap:DWOPdiv}{DW\-\_OP\-\_div} \\
785 The \livelink{chap:DWOPdiv}{DW\-\_OP\-\_div} operation pops the top two stack values, divides the former second entry by
786 the former top of the stack using signed division, and pushes the result.
787
788 \item \livetarg{chap:DWOPminus}{DW\-\_OP\-\_minus} \\
789 The \livelink{chap:DWOPminus}{DW\-\_OP\-\_minus} operation pops the top two stack values, subtracts the former top of the
790 stack from the former second entry, and pushes the result.
791
792 \item \livetarg{chap:DWOPmod}{DW\-\_OP\-\_mod}\\
793 The \livelink{chap:DWOPmod}{DW\-\_OP\-\_mod} operation pops the top two stack values and pushes the result of the
794 calculation: former second stack entry modulo the former top of the stack.
795
796 \item \livetarg{chap:DWOPmul}{DW\-\_OP\-\_mul} \\
797 The \livelink{chap:DWOPmul}{DW\-\_OP\-\_mul} operation pops the top two stack entries, multiplies them together, and
798 pushes the result.
799
800 \item  \livetarg{chap:DWOPneg}{DW\-\_OP\-\_neg} \\
801 The \livelink{chap:DWOPneg}{DW\-\_OP\-\_neg} operation pops the top stack entry, interprets
802 it as a signed value and pushes its negation. If the negation
803 cannot be represented, the result is undefined.
804
805 \item  \livetarg{chap:DWOPnot}{DW\-\_OP\-\_not} \\
806 The \livelink{chap:DWOPnot}{DW\-\_OP\-\_not} operation pops the top stack entry, and pushes
807 its bitwise complement.
808
809 \item  \livetarg{chap:DWOPor}{DW\-\_OP\-\_or} \\
810 The \livelink{chap:DWOPor}{DW\-\_OP\-\_or} operation pops the top two stack entries, performs
811 a bitwise or operation on the two, and pushes the result.
812
813 \item  \livetarg{chap:DWOPplus}{DW\-\_OP\-\_plus} \\
814 The \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus} operation pops the top two stack entries,
815 adds them together, and pushes the result.
816
817 \item  \livetarg{chap:DWOPplusuconst}{DW\-\_OP\-\_plus\-\_uconst} \\
818 The \livelink{chap:DWOPplusuconst}{DW\-\_OP\-\_plus\-\_uconst} operation pops the top stack entry,
819 adds it to the unsigned LEB128 constant operand and pushes
820 the result.  This operation is supplied specifically to be
821 able to encode more field offsets in two bytes than can be
822 done with “\livelink{chap:DWOPlit}{DW\-\_OP\-\_litn}n \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}”.
823
824 \item \livetarg{chap:DWOPshl}{DW\-\_OP\-\_shl} \\
825 The \livelink{chap:DWOPshl}{DW\-\_OP\-\_shl} operation pops the top two stack entries,
826 shifts the former second entry left (filling with zero bits)
827 by the number of bits specified by the former top of the stack,
828 and pushes the result.
829
830 \item \livetarg{chap:DWOPshr}{DW\-\_OP\-\_shr} \\
831 The \livelink{chap:DWOPshr}{DW\-\_OP\-\_shr} operation pops the top two stack entries,
832 shifts the former second entry right logically (filling with
833 zero bits) by the number of bits specified by the former top
834 of the stack, and pushes the result.
835
836 \item \livetarg{chap:DWOPshra}{DW\-\_OP\-\_shra} \\
837 The \livelink{chap:DWOPshra}{DW\-\_OP\-\_shra} operation pops the top two stack entries,
838 shifts the former second entry right arithmetically (divide
839 the magnitude by 2, keep the same sign for the result) by
840 the number of bits specified by the former top of the stack,
841 and pushes the result.
842
843 \item \livetarg{chap:DWOPxor}{DW\-\_OP\-\_xor} \\
844 The \livelink{chap:DWOPxor}{DW\-\_OP\-\_xor} operation pops the top two stack entries,
845 performs a bitwise exclusive\dash or operation on the two, and
846 pushes the result.
847
848 \end{enumerate}
849
850 \subsubsection{Control Flow Operations}
851 \label{chap:controlflowoperations}
852 The following operations provide simple control of the flow of a DWARF expression.
853 \begin{enumerate}[1]
854 \item  \livetarg{chap:DWOPle}{DW\-\_OP\-\_le}, \livetarg{chap:DWOPge}{DW\-\_OP\-\_ge}, \livetarg{chap:DWOPeq}{DW\-\_OP\-\_eq}, \livetarg{chap:DWOPlt}{DW\-\_OP\-\_lt}, \livetarg{chap:DWOPgt}{DW\-\_OP\-\_gt}, \livetarg{chap:DWOPne}{DW\-\_OP\-\_ne} \\
855 The six relational operators each:
856 \begin{itemize}
857 \item pop the top two stack values,
858
859 \item compare the operands:
860 \textless~former second entry~\textgreater  \textless~relational operator~\textgreater \textless~former top entry~\textgreater
861
862 \item push the constant value 1 onto the stack 
863 if the result of the operation is true or the
864 constant value 0 if the result of the operation is false.
865 \end{itemize}
866
867 Comparisons are performed as signed operations. The six
868 operators are \livelink{chap:DWOPle}{DW\-\_OP\-\_le} (less than or equal to), \livelink{chap:DWOPge}{DW\-\_OP\-\_ge}
869 (greater than or equal to), \livelink{chap:DWOPeq}{DW\-\_OP\-\_eq} (equal to), \livelink{chap:DWOPlt}{DW\-\_OP\-\_lt} (less
870 than), \livelink{chap:DWOPgt}{DW\-\_OP\-\_gt} (greater than) and \livelink{chap:DWOPne}{DW\-\_OP\-\_ne} (not equal to).
871
872 \item \livetarg{chap:DWOPskip}{DW\-\_OP\-\_skip} \\
873 \livelink{chap:DWOPskip}{DW\-\_OP\-\_skip} is an unconditional branch. Its single operand
874 is a 2\dash byte signed integer constant. The 2\dash byte constant is
875 the number of bytes of the DWARF expression to skip forward
876 or backward from the current operation, beginning after the
877 2\dash byte constant.
878
879 \item \livetarg{chap:DWOPbra}{DW\-\_OP\-\_bra} \\
880 \livelink{chap:DWOPbra}{DW\-\_OP\-\_bra} is a conditional branch. Its single operand is a
881 2\dash byte signed integer constant.  This operation pops the
882 top of stack. If the value popped is not the constant 0,
883 the 2\dash byte constant operand is the number of bytes of the
884 DWARF expression to skip forward or backward from the current
885 operation, beginning after the 2\dash byte constant.
886
887 % The following item does not correctly hyphenate leading
888 % to an overfull hbox and a visible artifact. 
889 % So we use \- to suggest hyphenation in this rare situation.
890 \item \livetarg{chap:DWOPcall2}{DW\-\_OP\-\_call2}, \livetarg{chap:DWOPcall4}{DW\-\_OP\-\_call4}, \livetarg{chap:DWOPcallref}{DW\-\_OP\-\_call\-\_ref} \\
891 \livelink{chap:DWOPcall2}{DW\-\_OP\-\_call2}, \livelink{chap:DWOPcall4}{DW\-\_OP\-\_call4}, and \livelink{chap:DWOPcallref}{DW\-\_OP\-\_call\-\_ref} perform
892 subroutine calls during evaluation of a DWARF expression or
893 location description. 
894 For \livelink{chap:DWOPcall2}{DW\-\_OP\-\_call2} and 
895 \livelink{chap:DWOPcall4}{DW\-\_OP\-\_call4}, 
896 the
897 operand is the 2\dash~ or 4\dash byte 
898 unsigned offset, respectively,
899 of a debugging information entry in the current compilation
900 unit. The \livelink{chap:DWOPcallref}{DW\-\_OP\-\_call\-\_ref} operator has a single operand. In the
901 32\dash bit DWARF format, the operand is a 4\dash byte unsigned value;
902 in the 64\dash bit DWARF format, it is an 8\dash byte unsigned value
903 (see Section \refersec{datarep:32bitand64bitdwarfformats}). 
904 The operand is used as the offset of a
905 debugging information entry in a .debug\_info or .debug\_types
906 section which may be contained in a shared object or executable
907 other than that containing the operator. For references from
908 one shared object or executable to another, the relocation
909 must be performed by the consumer.  
910
911 \textit{Operand interpretation of
912 \livelink{chap:DWOPcall2}{DW\-\_OP\-\_call2}, \livelink{chap:DWOPcall4}{DW\-\_OP\-\_call4} and \livelink{chap:DWOPcallref}{DW\-\_OP\-\_call\-\_ref} is exactly like
913 that for \livelink{chap:DWFORMref2}{DW\-\_FORM\-\_ref2}, \livelink{chap:DWFORMref4}{DW\-\_FORM\-\_ref4} and \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr},
914 respectively  
915 (see Section  \refersec{datarep:attributeencodings}).  
916 }
917
918 These operations transfer
919 control of DWARF expression evaluation to the 
920 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}
921 attribute of the referenced debugging information entry. If
922 there is no such attribute, then there is no effect. Execution
923 of the DWARF expression of a \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} attribute may add
924 to and/or remove from values on the stack. Execution returns
925 to the point following the call when the end of the attribute
926 is reached. Values on the stack at the time of the call may be
927 used as parameters by the called expression and values left on
928 the stack by the called expression may be used as return values
929 by prior agreement between the calling and called expressions.
930 \end{enumerate}
931
932
933 \subsubsection{Special Operations}
934 There is one special operation currently defined:
935 \begin{enumerate}[1]
936 \item \livetarg{chap:DWOPnop}{DW\-\_OP\-\_nop} \\
937 The \livelink{chap:DWOPnop}{DW\-\_OP\-\_nop} operation is a place holder. It has no effect
938 on the location stack or any of its values.
939
940 \end{enumerate}
941 \subsection{Example Stack Operations}
942 \textit {The stack operations defined in 
943 Section \refersec{chap:stackoperations}.
944 are fairly conventional, but the following
945 examples illustrate their behavior graphically.
946 }
947
948 \begin{tabular}{rrcrr} 
949  &Before & Operation&& After \\
950
951 0& 17& \livelink{chap:DWOPdup}{DW\-\_OP\-\_dup} &0 &17 \\
952 1&   29& &  1 & 17 \\
953 2& 1000 & & 2 & 29\\
954 & & &         3&1000\\
955 & & & & \\
956 0 & 17 & \livelink{chap:DWOPdrop}{DW\-\_OP\-\_drop} & 0 & 29 \\
957 1 &29  &            & 1 & 1000 \\
958 2 &1000& & &          \\
959
960 & & & & \\
961 0 & 17 & \livelink{chap:DWOPpick}{DW\-\_OP\-\_pick} & 0 & 1000 \\
962 1 & 29 & & 1&17 \\
963 2 &1000& &2&29 \\
964   &    & &3&1000 \\
965
966 & & & & \\
967 0&17& \livelink{chap:DWOPover}{DW\-\_OP\-\_over}&0&29 \\
968 1&29& &  1&17 \\
969 2&1000 & & 2&29\\
970  &     & & 3&1000 \\
971
972 & & & & \\
973 0&17& \livelink{chap:DWOPswap}{DW\-\_OP\-\_swap} &0&29 \\
974 1&29& &  1&17 \\
975 2&1000 & & 2&1000 \\
976
977 & & & & \\
978 0&17&\livelink{chap:DWOProt}{DW\-\_OP\-\_rot} & 0 &29 \\
979 1&29 & & 1 & 1000 \\
980 2& 1000 & &  2 & 17 \\
981 \end{tabular}
982
983 \section{Location Descriptions}
984 \label{chap:locationdescriptions}
985 \textit{ Debugging information must provide consumers a way to find
986 the location of program variables, determine the bounds
987 of dynamic arrays and strings, and possibly to find the
988 base address of a subroutine’s stack frame or the return
989 address of a subroutine. Furthermore, to meet the needs of
990 recent computer architectures and optimization techniques,
991 debugging information must be able to describe the location of
992 an object whose location changes over the object’s lifetime.}
993
994 Information about the location of program objects is provided
995 by location descriptions. Location descriptions can be either
996 of two forms:
997 \begin{enumerate}[1]
998 \item \textit{Single location descriptions}, which are a language independent representation of
999 addressing rules of arbitrary complexity built from 
1000 DWARF expressions (See section \refersec{chap:dwarfexpressions}) 
1001 and/or other
1002 DWARF operations specific to describing locations. They are
1003 sufficient for describing the location of any object as long
1004 as its lifetime is either static or the same as the lexical
1005 \livelink{chap:lexicalblock}{block} that owns it, 
1006 and it does not move during its lifetime.
1007
1008 Single location descriptions are of two kinds:
1009 \begin{enumerate}[a]
1010 \item Simple location descriptions, which describe the location
1011 of one contiguous piece (usually all) of an object. A simple
1012 location description may describe a location in addressable
1013 memory, or in a register, or the lack of a location (with or
1014 without a known value).
1015
1016 \item  Composite location descriptions, which describe an
1017 object in terms of pieces each of which may be contained in
1018 part of a register or stored in a memory location unrelated
1019 to other pieces.
1020
1021 \end{enumerate}
1022 \item \textit{Location lists}, which are used to describe
1023 objects that have a limited lifetime or change their location
1024 during their lifetime. Location lists are more completely
1025 described below.
1026
1027 \end{enumerate}
1028
1029 The two forms are distinguished in a context sensitive
1030 manner. As the value of an attribute, a location description
1031 is encoded using class \livelink{chap:exprloc}{exprloc}  
1032 and a location list is encoded
1033 using class \livelink{chap:loclistptr}{loclistptr} (which serves as an offset into a
1034 separate location list table).
1035
1036
1037 \subsection{Single Location Descriptions}
1038 A single location description is either:
1039
1040 \begin{enumerate}[1]
1041 \item A simple location description, representing an object
1042 which exists in one contiguous piece at the given location, or 
1043 \item A composite location description consisting of one or more
1044 simple location descriptions, each of which is followed by
1045 one composition operation. Each simple location description
1046 describes the location of one piece of the object; each
1047 composition operation describes which part of the object is
1048 located there. Each simple location description that is a
1049 DWARF expression is evaluated independently of any others
1050 (as though on its own separate stack, if any). 
1051 \end{enumerate}
1052
1053
1054
1055 \subsubsection{Simple Location Descriptions}
1056
1057 A simple location description consists of one 
1058 contiguous piece or all of an object or value.
1059
1060
1061 \paragraph{Memory Location Descriptions}
1062
1063 A memory location description consists of a non\dash empty DWARF
1064 expression (see 
1065 Section \refersec{chap:dwarfexpressions}
1066 ), whose value is the address of
1067 a piece or all of an object or other entity in memory.
1068
1069 \paragraph{Register Location Descriptions}
1070
1071 A register location description consists of a register name
1072 operation, which represents a piece or all of an object
1073 located in a given register.
1074
1075 \textit{Register location descriptions describe an object
1076 (or a piece of an object) that resides in a register, while
1077 the opcodes listed in 
1078 Section \refersec{chap:registerbasedaddressing}
1079 are used to describe an object (or a piece of
1080 an object) that is located in memory at an address that is
1081 contained in a register (possibly offset by some constant). A
1082 register location description must stand alone as the entire
1083 description of an object or a piece of an object.
1084 }
1085
1086 The following DWARF operations can be used to name a register.
1087
1088
1089 \textit{Note that the register number represents a DWARF specific
1090 mapping of numbers onto the actual registers of a given
1091 architecture. The mapping should be chosen to gain optimal
1092 density and should be shared by all users of a given
1093 architecture. It is recommended that this mapping be defined
1094 by the ABI authoring committee for each architecture.
1095 }
1096 \begin{enumerate}[1]
1097 \item \livetarg{chap:DWOPreg0}{DW\-\_OP\-\_reg0}, \livetarg{chap:DWOPreg1}{DW\-\_OP\-\_reg1}, ..., \livetarg{chap:DWOPreg31}{DW\-\_OP\-\_reg31} \\
1098 The \livetarg{chap:DWOPreg}{DW\-\_OP\-\_reg}n operations encode the names of up to 32
1099 registers, numbered from 0 through 31, inclusive. The object
1100 addressed is in register n.
1101
1102 \item \livetarg{chap:DWOPregx}{DW\-\_OP\-\_regx} \\
1103 The \livelink{chap:DWOPregx}{DW\-\_OP\-\_regx} operation has a single unsigned LEB128 literal
1104 operand that encodes the name of a register.  
1105 \end{enumerate}
1106
1107 \textit{These operations name a register location. To
1108 fetch the contents of a register, it is necessary to use
1109 one of the register based addressing operations, such as
1110 \livelink{chap:DWOPbregx}{DW\-\_OP\-\_bregx} 
1111 (Section \refersec{chap:registerbasedaddressing})}.
1112
1113
1114 \paragraph{Implicit Location Descriptions}
1115
1116 An implicit location description represents a piece or all
1117 of an object which has no actual location but whose contents
1118 are nonetheless either known or known to be undefined.
1119
1120 The following DWARF operations may be used to specify a value
1121 that has no location in the program but is a known constant
1122 or is computed from other locations and values in the program.
1123
1124 The following DWARF operations may be used to specify a value
1125 that has no location in the program but is a known constant
1126 or is computed from other locations and values in the program.
1127
1128 \begin{enumerate}[1]
1129 \item \livetarg{chap:DWOPimplicitvalue}{DW\-\_OP\-\_implicit\-\_value} \\
1130 The \livelink{chap:DWOPimplicitvalue}{DW\-\_OP\-\_implicit\-\_value} operation specifies an immediate value
1131 using two operands: an unsigned LEB128 length, followed by
1132 %FIXME: should this block be a reference? To what?
1133 a \nolink{block} representing the value in the memory representation
1134 of the target machine. The length operand gives the length
1135 in bytes of the \nolink{block}.
1136
1137 \item \livetarg{chap:DWOPstackvalue}{DW\-\_OP\-\_stack\-\_value} \\
1138 The \livelink{chap:DWOPstackvalue}{DW\-\_OP\-\_stack\-\_value} operation specifies that the object
1139 does not exist in memory but its value is nonetheless known
1140 and is at the top of the DWARF expression stack. In this form
1141 of location description, the DWARF expression represents the
1142 actual value of the object, rather than its location. The
1143 \livelink{chap:DWOPstackvalue}{DW\-\_OP\-\_stack\-\_value} operation terminates the expression.
1144 \end{enumerate}
1145
1146
1147 \paragraph{Empty Location Descriptions}
1148
1149 An empty location description consists of a DWARF expression
1150 containing no operations. It represents a piece or all of an
1151 object that is present in the source but not in the object code
1152 (perhaps due to optimization).
1153
1154 \subsubsection{Composite Location Descriptions}
1155 A composite location description describes an object or
1156 value which may be contained in part of a register or stored
1157 in more than one location. Each piece is described by a
1158 composition operation, which does not compute a value nor
1159 store any result on the DWARF stack. There may be one or
1160 more composition operations in a single composite location
1161 description. A series of such operations describes the parts
1162 of a value in memory address order.
1163
1164 Each composition operation is immediately preceded by a simple
1165 location description which describes the location where part
1166 of the resultant value is contained.
1167
1168 \begin{enumerate}[1]
1169 \item \livetarg{chap:DWOPpiece}{DW\-\_OP\-\_piece} \\
1170 The \livelink{chap:DWOPpiece}{DW\-\_OP\-\_piece} operation takes a single operand, which is an
1171 unsigned LEB128 number.  The number describes the size in bytes
1172 of the piece of the object referenced by the preceding simple
1173 location description. If the piece is located in a register,
1174 but does not occupy the entire register, the placement of
1175 the piece within that register is defined by the ABI.
1176
1177 \textit{Many compilers store a single variable in sets of registers,
1178 or store a variable partially in memory and partially in
1179 registers. \livelink{chap:DWOPpiece}{DW\-\_OP\-\_piece} provides a way of describing how large
1180 a part of a variable a particular DWARF location description
1181 refers to. }
1182
1183 \item \livetarg{chap:DWOPbitpiece}{DW\-\_OP\-\_bit\-\_piece} \\
1184 The \livelink{chap:DWOPbitpiece}{DW\-\_OP\-\_bit\-\_piece} operation takes two operands. The first
1185 is an unsigned LEB128 number that gives the size in bits
1186 of the piece. The second is an unsigned LEB128 number that
1187 gives the offset in bits from the location defined by the
1188 preceding DWARF location description.  
1189
1190 Interpretation of the
1191 offset depends on the kind of location description. If the
1192 location description is empty, the offset doesn’t matter and
1193 the \livelink{chap:DWOPbitpiece}{DW\-\_OP\-\_bit\-\_piece} operation describes a piece consisting
1194 of the given number of bits whose values are undefined. If
1195 the location is a register, the offset is from the least
1196 significant bit end of the register. If the location is a
1197 memory address, the \livelink{chap:DWOPbitpiece}{DW\-\_OP\-\_bit\-\_piece} operation describes a
1198 sequence of bits relative to the location whose address is
1199 on the top of the DWARF stack using the bit numbering and
1200 direction conventions that are appropriate to the current
1201 language on the target system. If the location is any implicit
1202 value or stack value, the \livelink{chap:DWOPbitpiece}{DW\-\_OP\-\_bit\-\_piece} operation describes
1203 a sequence of bits using the least significant bits of that
1204 value.  
1205 \end{enumerate}
1206
1207 \textit{\livelink{chap:DWOPbitpiece}{DW\-\_OP\-\_bit\-\_piece} is used instead of \livelink{chap:DWOPpiece}{DW\-\_OP\-\_piece} when
1208 the piece to be assembled into a value or assigned to is not
1209 byte-sized or is not at the start of a register or addressable
1210 unit of memory.}
1211
1212
1213
1214
1215 \subsubsection{Example Single Location Descriptions}
1216
1217 Here are some examples of how DWARF operations are used to form location descriptions:
1218
1219 \livetarg{chap:DWOPreg3}{DW\-\_OP\-\_reg3}
1220 \begin{myindentpara}{1cm}
1221 The value is in register 3.
1222 \end{myindentpara}
1223
1224 \livelink{chap:DWOPregx}{DW\-\_OP\-\_regx} 54
1225 \begin{myindentpara}{1cm}
1226 The value is in register 54.
1227 \end{myindentpara}
1228
1229 \livelink{chap:DWOPaddr}{DW\-\_OP\-\_addr} 0x80d0045c
1230 \begin{myindentpara}{1cm}
1231 The value of a static variable is at machine address 0x80d0045c.
1232 \end{myindentpara}
1233
1234 \livetarg{chap:DWOPbreg11}{DW\-\_OP\-\_breg11} 44
1235 \begin{myindentpara}{1cm}
1236 Add 44 to the value in register 11 to get the address of an automatic
1237 variable instance.
1238 \end{myindentpara}
1239
1240 \livelink{chap:DWOPfbreg}{DW\-\_OP\-\_fbreg} -50
1241 \begin{myindentpara}{1cm}
1242 Given a \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} value of ``\livelink{chap:DWOPbreg31}{DW\-\_OP\-\_breg31} 64,''this example
1243 computes the address of a local variable that is -50 bytes from a
1244 logical frame pointer that is computed by adding 64 to the current
1245 stack pointer (register 31).
1246 \end{myindentpara}
1247
1248 \livelink{chap:DWOPbregx}{DW\-\_OP\-\_bregx} 54 32 \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref}
1249 \begin{myindentpara}{1cm}
1250 A call-by-reference parameter whose address is in the word 32 bytes
1251 from where register 54 points.
1252 \end{myindentpara}
1253
1254 \livelink{chap:DWOPplusuconst}{DW\-\_OP\-\_plus\-\_uconst} 4
1255 \begin{myindentpara}{1cm}
1256 A structure member is four bytes from the start of the structure
1257 instance. The base address is assumed to be already on the stack.
1258 \end{myindentpara}
1259
1260 \livelink{chap:DWOPreg3}{DW\-\_OP\-\_reg3} \livelink{chap:DWOPpiece}{DW\-\_OP\-\_piece} 4 \livetarg{chap:DWOPreg10}{DW\-\_OP\-\_reg10} \livelink{chap:DWOPpiece}{DW\-\_OP\-\_piece} 2
1261 \begin{myindentpara}{1cm}
1262 A variable whose first four bytes reside in register 3 and whose next
1263 two bytes reside in register 10.
1264 \end{myindentpara}
1265
1266 \livelink{chap:DWOPreg0}{DW\-\_OP\-\_reg0} \livelink{chap:DWOPpiece}{DW\-\_OP\-\_piece} 4 \livelink{chap:DWOPpiece}{DW\-\_OP\-\_piece} 4 \livelink{chap:DWOPfbreg}{DW\-\_OP\-\_fbreg} -12 \livelink{chap:DWOPpiece}{DW\-\_OP\-\_piece} 4
1267 \begin{myindentpara}{1cm}
1268 A twelve byte value whose first four bytes reside in register zero,
1269 whose middle four bytes are unavailable (perhaps due to optimization),
1270 and whose last four bytes are in memory, 12 bytes before the frame
1271 base.
1272 \end{myindentpara}
1273
1274 \livelink{chap:DWOPbreg1}{DW\-\_OP\-\_breg1} 0 \livetarg{chap:DWOPbreg2}{DW\-\_OP\-\_breg2} 0 \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus} \livelink{chap:DWOPstackvalue}{DW\-\_OP\-\_stack\-\_value}
1275 \begin{myindentpara}{1cm}
1276 Add the contents of r1 and r2 to compute a value. This value is the
1277 “contents” of an otherwise anonymous location.
1278 \end{myindentpara}
1279
1280 \livelink{chap:DWOPlit1}{DW\-\_OP\-\_lit1} \livelink{chap:DWOPstackvalue}{DW\-\_OP\-\_stack\-\_value} \livelink{chap:DWOPpiece}{DW\-\_OP\-\_piece} a \\
1281 \livetarg{chap:DWOPbreg3}{DW\-\_OP\-\_breg3} 0 \livetarg{chap:DWOPbreg4}{DW\-\_OP\-\_breg4} 0 \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus} \livelink{chap:DWOPstackvalue}{DW\-\_OP\-\_stack\-\_value} \livelink{chap:DWOPpiece}{DW\-\_OP\-\_piece} 4
1282 \begin{myindentpara}{1cm}
1283 The object value is found in an anonymous (virtual) location whose
1284 value consists of two parts, given in memory address order: the 4 byte
1285 value 1 followed by the four byte value computed from the sum of the
1286 contents of r3 and r4.
1287 \end{myindentpara}
1288
1289
1290 \subsection{Location Lists}
1291 \label{chap:locationlists}
1292 Location lists are used in place of location expressions
1293 whenever the object whose location is being described
1294 can change location during its lifetime. Location lists
1295 are contained in a separate object file section called
1296 .debug\_loc. A location list is indicated by a location
1297 attribute whose value is an offset from the beginning of
1298 the .debug\_loc section to the first byte of the list for the
1299 object in question.
1300
1301 Each entry in a location list is either a location 
1302 \addtoindexi{list}{address selection|see{base address selection}} 
1303 entry,
1304
1305 \addtoindexi{base}{base address selection entry!in location list} 
1306 address selection entry, or an end of list entry.
1307
1308 A location list entry consists of:
1309
1310 \begin{enumerate}[1]
1311 \item A beginning address offset. 
1312 This address offset has the size of an address and is
1313 relative to the applicable base address of the compilation
1314 unit referencing this location list. It marks the beginning
1315 of the address 
1316 \addtoindexi{range}{address range!in location list} 
1317 over which the location is valid.
1318
1319 \item An ending address offset.  This address offset again
1320 has the size of an address and is relative to the applicable
1321 base address of the compilation unit referencing this location
1322 list. It marks the first address past the end of the address
1323 range over which the location is valid. The ending address
1324 must be greater than or equal to the beginning address.
1325
1326 \textit{A location list entry (but not a base address selection or end of list entry) whose beginning
1327 and ending addresses are equal has no effect because the size of the range covered by such
1328 an entry is zero.}
1329
1330 \item A single location description 
1331 describing the location of the object over the range specified by
1332 the beginning and end addresses.
1333 \end{enumerate}
1334
1335 The applicable base address of a location list entry is
1336 determined by the closest preceding base address selection
1337 entry (see below) in the same location list. If there is
1338 no such selection entry, then the applicable base address
1339 defaults to the base address of the compilation unit (see
1340 Section \refersec{chap:normalandpartialcompilationunitentries}).  
1341 In the case of a compilation unit where all of
1342 the machine code is contained in a single contiguous section,
1343 no base address selection entry is needed.
1344
1345 Address ranges may overlap. When they do, they describe a
1346 situation in which an object exists simultaneously in more than
1347 one place. If all of the address ranges in a given location
1348 list do not collectively cover the entire range over which the
1349 object in question is defined, it is assumed that the object is
1350 not available for the portion of the range that is not covered.
1351
1352 A base 
1353 \addtoindexi{address}{address selection|see{base address selection}}
1354 selection 
1355 \addtoindexi{entry}{base address selection entry!in location list}:
1356 \begin{enumerate}[1]
1357 \item The value of the largest representable 
1358 address offset (for example, 0xffffffff when the size of
1359 an address is 32 bits).
1360 \item An address, which defines the 
1361 appropriate base address for use in interpreting the beginning
1362 and ending address offsets of subsequent entries of the location list.
1363 \end{enumerate}
1364
1365
1366 \textit{A base address selection entry 
1367 affects only the list in which it is contained.}
1368
1369 The end of any given location list is marked by an end of
1370 list entry, which consists of a 0 for the beginning address
1371 offset and a 0 for the ending address offset. A location list
1372 containing only an end of list entry describes an object that
1373 exists in the source code but not in the executable program.
1374
1375 Neither a base address selection entry nor an end of list
1376 entry includes a location description.
1377
1378 \textit{A base address selection entry and an end of list
1379 entry for a location list are identical to a base address
1380 selection entry and end of list entry, respectively, for a
1381 range list 
1382 (see Section \refersec{chap:noncontiguousaddressranges}) 
1383 in interpretation
1384 and representation.}
1385
1386
1387
1388
1389
1390
1391 \section{Types of Program Entities}
1392 \label{chap:typesofprogramentities}
1393 Any 
1394 \hypertarget{chap:DWATtypetypeofdeclaration}
1395 debugging information entry describing a declaration that
1396 has a type has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute, whose value is a
1397 reference to another debugging information entry. The entry
1398 referenced may describe a base type, that is, a type that is
1399 not defined in terms of other data types, or it may describe a
1400 user-defined type, such as an array, structure or enumeration.
1401 Alternatively, the entry referenced may describe a type
1402 modifier, such as constant, packed, pointer, reference or
1403 volatile, which in turn will reference another entry describing
1404 a type or type modifier (using a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute of its
1405 own). See 
1406 Section  \refersec{chap:typeentries} 
1407 for descriptions of the entries describing
1408 base types, user-defined types and type modifiers.
1409
1410
1411
1412 \section{Accessibility of Declarations}
1413 \label{chap:accessibilityofdeclarations}
1414 \textit{Some languages, notably C++ and Ada, have the concept of
1415 the accessibility of an object or of some other program
1416 entity. The accessibility specifies which classes of other
1417 program objects are permitted access to the object in question.}
1418
1419 The accessibility of a declaration is 
1420 \hypertarget{chap:DWATaccessibilitycandadadeclarations}
1421 represented by a 
1422 \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} attribute, whose
1423 value is a constant drawn from the set of codes listed in Figure 
1424 \ref{fig:accessibilitycodes}.
1425
1426 \begin{figure}[here]
1427 \begin{description}
1428 \centering
1429 \item [\livetarg{chap:DWACCESSpublic}{DW\-\_ACCESS\-\_public}]
1430 \item [\livetarg{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private}]
1431 \item [\livetarg{chap:DWACCESSprotected}{DW\-\_ACCESS\-\_protected}]
1432 \end{description}
1433 \caption{Accessibility codes}
1434 \label{fig:accessibilitycodes}
1435 \end{figure}
1436
1437 \section{Visibility of Declarations}
1438 \label{chap:visibilityofdeclarations}
1439
1440 \textit{Several languages (such as Modula-2) 
1441 have the concept of the visibility of a declaration. The
1442 visibility specifies which declarations are to be 
1443 visible outside of the entity in which they are
1444 declared.}
1445
1446 The 
1447 \hypertarget{chap:DWATvisibilityvisibilityofdeclaration}
1448 visibility of a declaration is represented 
1449 by a \livelink{chap:DWATvisibility}{DW\-\_AT\-\_visibility} attribute, whose value is a
1450 constant drawn from the set of codes listed in 
1451 Figure \ref{fig:visibilitycodes}.
1452
1453 \begin{figure}[here]
1454 \begin{description}
1455 \centering
1456 \item [\livetarg{chap:DWVISlocal}{DW\-\_VIS\-\_local}]
1457 \item [\livetarg{chap:DWVISexported}{DW\-\_VIS\-\_exported}]
1458 \item [\livetarg{chap:DWVISqualified}{DW\-\_VIS\-\_qualified}]
1459 \end{description}
1460 \caption{Visibility codes}
1461 \label{fig:visibilitycodes}
1462 \end{figure}
1463
1464 \section{Virtuality of Declarations}
1465 \label{chap:virtualityofdeclarations}
1466 \textit{C++ provides for virtual and pure virtual structure or class
1467 member functions and for virtual base classes.}
1468
1469 The 
1470 \hypertarget{chap:DWATvirtualityvirtualityindication}
1471 virtuality of a declaration is represented by a
1472 \livelink{chap:DWATvirtuality}{DW\-\_AT\-\_virtuality} attribute, whose value is a constant drawn
1473 from the set of codes listed in 
1474 Figure \ref{fig:virtualitycodes}.
1475
1476 \begin{figure}[here]
1477 \begin{description}
1478 \centering
1479 \item [\livetarg{chap:DWVIRTUALITYnone}{DW\-\_VIRTUALITY\-\_none}]
1480 \item [\livetarg{chap:DWVIRTUALITYvirtual}{DW\-\_VIRTUALITY\-\_virtual}]
1481 \item [\livetarg{chap:DWVIRTUALITYpurevirtual}{DW\-\_VIRTUALITY\-\_pure\-\_virtual}]
1482 \end{description}
1483 \caption{Virtuality codes}
1484 \label{fig:virtualitycodes}
1485 \end{figure}
1486
1487 \section{Artificial Entries}
1488 \label{chap:artificialentries}
1489 \textit{A compiler may wish to generate debugging information entries
1490 for objects or types that were not actually declared in the
1491 source of the application. An example is a formal parameter
1492 entry to represent the hidden this parameter that most C++
1493 implementations pass as the first argument to non-static member
1494 functions.}  
1495
1496 Any debugging information entry representing the
1497 declaration of an object or type artificially generated by
1498 a compiler and not explicitly declared by the source program
1499 \hypertarget{chap:DWATartificialobjectsortypesthat}
1500 may have a 
1501 \livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial} attribute, 
1502 which is a \livelink{chap:flag}{flag}.
1503
1504 \section{Segmented Addresses}
1505 \label{chap:segmentedaddresses}
1506 \textit{In some systems, addresses are specified as offsets within a
1507 given 
1508 \addtoindexx{address space!segmented}
1509 segment rather than as locations within a single flat
1510 \addtoindexx{address space!flat}.
1511 address space.}
1512
1513 Any debugging information entry that contains a description
1514 \hypertarget{chap:DWATsegmentaddressinginformation}
1515 of the location of an object or subroutine may have
1516
1517 \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}
1518 attribute, whose value is a location
1519 description. The description evaluates to the segment selector
1520 of the item being described. If the entry containing the
1521 \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute has a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}, \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc},
1522 \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} or \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute, or a location
1523 description that evaluates to an address, then those address
1524 values represent the offset portion of the address within
1525 the segment specified by \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}.
1526
1527 If an entry has no \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute, it inherits
1528 the segment value from its parent entry.  If none of the
1529 entries in the chain of parents for this entry back to
1530 its containing compilation unit entry have \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}
1531 attributes, then the entry is assumed to exist within a flat
1532 address space. Similarly, if the entry has a \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}
1533 attribute containing an empty location description, that
1534 entry is assumed to exist within a 
1535 \addtoindexi{flat}{address space!flat}.
1536 address space.
1537
1538 \textit{Some systems support different classes of 
1539 addresses
1540 \addtoindexx{address class!attribute}. 
1541 The
1542 address class may affect the way a pointer is dereferenced
1543 or the way a subroutine is called.}
1544
1545
1546 Any debugging information entry representing a pointer or
1547 reference type or a subroutine or subroutine type may 
1548 have a 
1549 \livelink{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class}
1550 attribute, whose value is an integer
1551 constant.  The set of permissible values is specific to
1552 each target architecture. The value \livetarg{chap:DWADDRnone}{DW\-\_ADDR\-\_none}, 
1553 however,
1554 is common to all encodings, and means that no address class
1555 has been specified.
1556
1557 \textit {For example, the Intel386 ™ processor might use the following values:}
1558
1559 \begin{figure}[here]
1560 \centering
1561 \begin{tabular}{lll} 
1562 Name&Value&Meaning  \\
1563 \hline
1564 \textit{DW\-\_ADDR\-\_none}&   0 & \textit{no class specified} \\
1565 \textit{DW\-\_ADDR\-\_near16}& 1 & \textit{16\dash bit offset, no segment} \\
1566 \textit{DW\-\_ADDR\-\_far16}&  2 & \textit{16\dash bit offset, 16\dash bit segment} \\
1567 \textit{DW\-\_ADDR\-\_huge16}& 3 & \textit{16\dash bit offset, 16\dash bit segment} \\
1568 \textit{DW\-\_ADDR\-\_near32}& 4 & \textit{32\dash bit offset, no segment} \\
1569 \textit{DW\-\_ADDR\-\_far32}&  5 & \textit{32\dash bit offset, 16\dash bit segment}
1570 \end{tabular}
1571 \caption{Example address class codes}
1572 \label{fig:inteladdressclasstable}
1573 \end{figure}
1574
1575 \section{Non-Defining Declarations and Completions}
1576 \label{nondefiningdeclarationsandcompletions}
1577 A debugging information entry representing a program entity
1578 typically represents the defining declaration of that
1579 entity. In certain contexts, however, a debugger might need
1580 information about a declaration of an entity that is not
1581 also a definition, or is otherwise incomplete, to evaluate
1582 \hypertarget{chap:DWATdeclarationincompletenondefiningorseparateentitydeclaration}
1583 an expression correctly.
1584
1585 \textit{As an example, consider the following fragment of C code:}
1586
1587 \begin{lstlisting}
1588 void myfunc()
1589 {
1590   int x;
1591   {
1592     extern float x;
1593     g(x);
1594   }
1595 }
1596 \end{lstlisting}
1597
1598
1599 \textit{C scoping rules require that the 
1600 value of the variable x passed to the function g is the value of the
1601 global variable x rather than of the local version.}
1602
1603 \subsection{Non-Defining Declarations}
1604 A debugging information entry that represents a non-defining or otherwise incomplete
1605 declaration of a program entity has a 
1606 \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} 
1607 attribute, which is a 
1608 \livelink{chap:flag}{flag}.
1609
1610 \subsection{Declarations Completing Non-Defining Declarations}
1611 A debugging information entry that represents a 
1612 \hypertarget{chap:DWATspecificationincompletenondefiningorseparatedeclaration}
1613 declaration that completes another (earlier) 
1614 non\dash defining declaration may have a 
1615 \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification}
1616 attribute whose value is a reference to
1617 the debugging information entry representing the non-defining declaration. A debugging
1618 information entry with a 
1619 \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} 
1620 attribute does not need to duplicate information
1621 provided by the debugging information entry referenced by that specification attribute.
1622
1623 It is not the case that all attributes of the debugging information entry referenced by a
1624 \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute 
1625 apply to the referring debugging information entry.
1626
1627 \textit{For example,
1628 \livelink{chap:DWATsibling}{DW\-\_AT\-\_sibling} and 
1629 \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} 
1630 clearly cannot apply to a referring
1631 entry.}
1632
1633
1634
1635 \section{Declaration Coordinates}
1636 \label{chap:declarationcoordinates}
1637 \textit{It is sometimes useful in a debugger to be able to associate
1638 a declaration with its occurrence in the program source.
1639 }
1640
1641 Any debugging information 
1642 \hypertarget{chap:DWATdeclfilefilecontainingsourcedeclaration}
1643 entry 
1644 \hypertarget{chap:DWATdecllinelinenumberofsourcedeclaration}
1645 representing 
1646 \hypertarget{chap:DWATdeclcolumncolumnpositionofsourcedeclaration}
1647 the
1648 declaration of an object, module, subprogram or type may have
1649 \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file}, \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} and \livelink{chap:DWATdeclcolumn}{DW\-\_AT\-\_decl\-\_column}
1650 attributes each of whose value is an unsigned integer constant.
1651
1652 The value of the \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file} attribute corresponds to
1653 a file number from the line number information table for the
1654 compilation unit containing the debugging information entry and
1655 represents the source file in which the declaration appeared
1656 (see Section 6.2). The value 0 indicates that no source file
1657 has been specified.
1658
1659 The value of the \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} attribute represents
1660 the source line number at which the first character of
1661 the identifier of the declared object appears. The value 0
1662 indicates that no source line has been specified.
1663
1664 The value of the \livelink{chap:DWATdeclcolumn}{DW\-\_AT\-\_decl\-\_column} attribute represents
1665 the source column number at which the first character of
1666 the identifier of the declared object appears. The value 0
1667 indicates that no column has been specified.
1668
1669 \section{Identifier Names}
1670 \label{chap:identifiernames}
1671 Any 
1672 \hypertarget{chap:DWATnamenameofdeclaration}
1673 debugging information entry representing a program entity
1674 that has been given a name may have a 
1675 \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute,
1676 whose value is a string representing the name as it appears in
1677 the source program. A debugging information entry containing
1678 no name attribute, or containing a name attribute whose value
1679 consists of a name containing a single null byte, represents
1680 a program entity for which no name was given in the source.
1681
1682 \textit{Because the names of program objects described by DWARF are the
1683 names as they appear in the source program, implementations
1684 of language translators that use some form of mangled name
1685 (as do many implementations of C++) should use the unmangled
1686 form of the name in the DWARF \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute,
1687 including the keyword operator (in names such as “operator
1688 +”), if present. See also 
1689 Section \refersec{chap:linkagenames} regarding the use
1690 of \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} for mangled names. Sequences of
1691 multiple whitespace characters may be compressed.}
1692
1693 \section{Data Locations and DWARF Procedures}
1694 Any debugging information entry describing a data object (which
1695 \hypertarget{chap:DWATlocationdataobjectlocation}
1696 includes variables and parameters) or 
1697 common \livelink{chap:commonblockentry}{block}
1698 may have a
1699 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} attribute, whose value is a location description
1700 (see Section 2.6).  
1701
1702 A DWARF procedure is represented by any
1703 kind of debugging information entry that has a \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}
1704 attribute. If a suitable entry is not otherwise available,
1705 a DWARF procedure can be represented using a debugging
1706 information entry with the 
1707 tag \livetarg{chap:DWTAGdwarfprocedure}{DW\-\_TAG\-\_dwarf\-\_procedure}
1708 together with a \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} attribute.  
1709
1710 A DWARF procedure
1711 is called by a \livelink{chap:DWOPcall2}{DW\-\_OP\-\_call2}, 
1712 \livelink{chap:DWOPcall4}{DW\-\_OP\-\_call4} or 
1713 \livelink{chap:DWOPcallref}{DW\-\_OP\-\_call\-\_ref}
1714 DWARF expression operator 
1715 (see Section \refersec{chap:controlflowoperations}).
1716
1717 \section{Code Addresses and Ranges}
1718 \label{chap:codeaddressesandranges}
1719 Any debugging information entry describing an entity that has
1720 a machine code address or range of machine code addresses,
1721 which includes compilation units, module initialization,
1722 \hypertarget{chap:DWATrangesnoncontiguousrangeofcodeaddresses}
1723 subroutines, ordinary \livelink{chap:lexicalblock}{block}, 
1724 try/catch \nolink{blocks} (see Section\refersec{chap:tryandcatchblockentries}), 
1725 labels 
1726 \hypertarget{chap:DWATlowpccodeaddressorrangeofaddresses}
1727 and
1728 \hypertarget{chap:DWAThighpccontinguousrangeofcodeaddresses}
1729 the like, may have
1730
1731 \begin{itemize}
1732 \item A \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of 
1733 attributes for a single contiguous range of
1734 addresses, or
1735
1736 \item A \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute for a non-contiguous range of addresses.
1737 \end{itemize}
1738
1739 In addition, a non-contiguous range of 
1740 addresses may also be specified for the
1741 \livelink{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope} attribute.
1742 If an entity has no associated machine code, 
1743 none of these attributes are specified.
1744
1745 \subsection{Single Address} 
1746 When there is a single address associated with an entity,
1747 such as a label or alternate entry point of a subprogram,
1748 the entry has a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute whose value is the
1749 relocated address for the entity.  While the \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc}
1750 attribute might also seem appropriate for this purpose,
1751 historically the \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute was used before the
1752 \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} was introduced (in DWARF Version 3). There is
1753 insufficient reason to change this.
1754
1755 \subsection{Continuous Address Range}
1756 \label{chap:contiguousaddressranges}
1757 When the set of addresses of a debugging information entry can
1758 be described as a single continguous range, the entry may have
1759 a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of attributes. The value
1760 of the \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute is the relocated address of the
1761 first instruction associated with the entity. If the value of
1762 the \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} is of class address, it is the relocated
1763 address of the first location past the last instruction
1764 associated with the entity; if it is of class constant, the
1765 value is an unsigned integer offset which when added to the
1766 low PC gives the address of the first location past the last
1767 instruction associated with the entity.  The high PC value
1768 may be beyond the last valid instruction in the executable.
1769 The presence of low and high PC attributes for an entity
1770 implies that the code generated for the entity is contiguous
1771 and exists totally within the boundaries specified by those
1772 two attributes. If that is not the case, no low and high PC
1773 attributes should be produced.
1774
1775 \subsection{Non\dash Contiguous Address Ranges}
1776 \label{chap:noncontiguousaddressranges}
1777 When the set of addresses of a debugging information entry
1778 cannot be described as a single contiguous range, the entry has
1779 a \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute whose value is of class \livelink{chap:rangelistptr}{rangelistptr}
1780 and indicates the beginning of a range list. Similarly,
1781 a \livelink{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope} attribute may have a value of class
1782 \livelink{chap:rangelistptr}{rangelistptr} for the same reason.  
1783
1784 Range lists are contained
1785 in a separate object file section called .debug\_ranges. A
1786 range list is indicated by a \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute whose
1787 value is represented as an offset from the beginning of the
1788 .debug\_ranges section to the beginning of the range list.
1789
1790 Each entry in a range list is either a range list entry,
1791 a base address selection entry, or an end of list entry.
1792
1793 A range list entry consists of:
1794
1795 \begin{enumerate}[1]
1796 \item A beginning address offset. This address offset has the size of an address and is relative to
1797 the applicable base address of the compilation unit referencing this range list. It marks the
1798 beginning of an 
1799 \addtoindexi{address}{address range!in range list} 
1800 range.
1801
1802 \item An ending address offset. This address offset again has the size of an address and is relative
1803 to the applicable base address of the compilation unit referencing this range list. It marks the
1804 first address past the end of the address range.The ending address must be greater than or
1805 equal to the beginning address.
1806
1807 \textit{A range list entry (but not a base address selection or end of list entry) whose beginning and
1808 ending addresses are equal has no effect because the size of the range covered by such an
1809 entry is zero.}
1810 \end{enumerate}
1811
1812 The applicable base address of a range list entry is determined
1813 by the closest preceding base address selection entry (see
1814 below) in the same range list. If there is no such selection
1815 entry, then the applicable base address defaults to the base
1816 address of the compilation unit 
1817 (see Section \refersec{chap:normalandpartialcompilationunitentries}).
1818
1819 \textit{In the case of a compilation unit where all of the machine
1820 code is contained in a single contiguous section, no base
1821 address selection entry is needed.}
1822
1823 Address range entries in
1824 a range list may not overlap. There is no requirement that
1825 the entries be ordered in any particular way.
1826
1827 A base address selection entry consists of:
1828
1829 \begin{enumerate}[1]
1830 \item The value of the largest representable address offset (for example, 0xffffffff when the size of
1831 an address is 32 bits).
1832
1833 \item An address, which defines the appropriate base address for use in interpreting the beginning
1834 and ending address offsets of subsequent entries of the location list.
1835 \end{enumerate}
1836 \textit{A base address selection entry 
1837 affects only the list in which it is contained.}
1838
1839
1840 The end of any given range list is marked by an end of
1841 list entry, which consists of a 0 for the beginning address
1842 offset and a 0 for the ending address offset. A range list
1843 containing only an end of list entry describes an empty scope
1844 (which contains no instructions).
1845
1846 \textit{A base address selection entry and an end of list entry for
1847 a range list are identical to a base address selection entry
1848 and end of list entry, respectively, for a location list
1849 (see Section 2.6.2) in interpretation and representation.}
1850
1851
1852
1853 \section{Entry Address}
1854 \label{chap:entryaddress}
1855 \textit{The entry or first executable instruction generated
1856 for an entity, if applicable, is often the lowest addressed
1857 instruction of a contiguous range of instructions. In other
1858 cases, the entry address needs to be specified explicitly.}
1859
1860 Any debugging information entry describing an entity that has
1861 a range of code addresses, which includes compilation units,
1862 module initialization, subroutines, 
1863 ordinary \livelink{chap:lexicalblock}{block}, 
1864 try/catch \nolink{blocks} (see Section \refersec{chap:tryandcatchblockentries}),
1865 and the like, 
1866 may have a \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute to
1867 indicate the first executable instruction within that range
1868 of addresses. The value of the \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute is a
1869 relocated address. If no \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute is present,
1870 then the entry address is assumed to be the same as the
1871 value of the \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute, if present; otherwise,
1872 the entry address is unknown.
1873
1874 \section{Static and Dynamic Values of Attributes}
1875 \label{chap:staticanddynamicvaluesofattributes}
1876
1877 Some attributes that apply to types specify a property (such
1878 as the lower bound of an array) that is an integer value,
1879 where the value may be known during compilation or may be
1880 computed dynamically during execution.  The value of these
1881 attributes is determined based on the class as follows:
1882
1883 \begin{itemize}
1884 \item For a \livelink{chap:constant}{constant}, the value of the constant is the value of
1885 the attribute.
1886
1887 \item For a \livelink{chap:reference}{reference}, the
1888 value is a reference to another
1889 entity which specifies the value of the attribute.
1890
1891 \item For an \livelink{chap:exprloc}{exprloc}, the value is interpreted as a 
1892 DWARF expression; 
1893 evaluation of the expression yields the value of
1894 the attribute.
1895 \end{itemize}
1896
1897 \textit{
1898 Whether an attribute value can be dynamic depends on the
1899 rules of the applicable programming language.
1900 }
1901
1902 \textit{The applicable attributes include: 
1903 \livelink{chap:DWATallocated}{DW\-\_AT\-\_allocated},
1904 \livelink{chap:DWATassociated}{DW\-\_AT\-\_associated}, 
1905 \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset}, 
1906 \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size},
1907 \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}, 
1908 \livelink{chap:DWATcount}{DW\-\_AT\-\_count}, 
1909 \livelink{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound},
1910 \livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride}, 
1911 \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride}, 
1912 \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound} (and
1913 possibly others).}
1914
1915
1916 \section{Entity Descriptions}
1917 \textit{Some debugging information entries may describe entities
1918 in the program that are artificial, or which otherwise are
1919 ``named'' in ways which are not valid identifiers in the
1920 programming language. For example, several languages may
1921 capture or freeze the value of a variable at a particular
1922 point in the program. Ada 95 has package elaboration routines,
1923 type descriptions of the form typename’Class, and 
1924 ``access typename'' parameters.  }
1925
1926 Generally, any debugging information
1927 entry that 
1928 \hypertarget{chap:DWATdescriptionartificialnameordescription}
1929 has, or may have, a 
1930 \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, may
1931 also have a 
1932 \livelink{chap:DWATdescription}{DW\-\_AT\-\_description} attribute whose value is a
1933 null-terminated string providing a description of the entity.
1934
1935
1936 \textit{It is expected that a debugger will only display these
1937 descriptions as part of the description of other entities. It
1938 should not accept them in expressions, nor allow them to be
1939 assigned, or the like.}
1940
1941 \section{Byte and Bit Sizes}
1942 \label{chap:byteandbitsizes}
1943 % Some trouble here with hbox full, so we try optional word breaks.
1944 Many debugging information entries allow either a
1945 \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute or a \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute,
1946 whose integer constant value 
1947 (see \refersec{chap:staticanddynamicvaluesofattributes}) 
1948 specifies an
1949 amount of storage. The value of the \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute
1950 is interpreted in bytes and the value of the \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}
1951 attribute is interpreted in bits.  
1952
1953 Similarly, the integer
1954 constant value of a \livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride} attribute is interpreted
1955 in bytes and the integer constant value of a \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride}
1956 attribute is interpreted in bits.
1957
1958 \section{Linkage Names}
1959 \label{chap:linkagenames}
1960 \textit{Some language implementations, notably C++ and similar
1961 languages, make use of implementation defined names within
1962 object files that are different from the identifier names
1963 (see \refersec{chap:identifiernames}) of entities as they appear in the
1964 source. Such names, sometimes known as mangled names,
1965 are used in various ways, such as: to encode additional
1966 information about an entity, to distinguish multiple entities
1967 that have the same name, and so on. When an entity has an
1968 associated distinct linkage name it may sometimes be useful
1969 for a producer to include this name in the DWARF description
1970 of the program to facilitate consumer access to and use of
1971 object file information about an entity and/or information
1972 \hypertarget{chap:DWATlinkagenameobjectfilelinkagenameofanentity}
1973 that is encoded in the linkage name itself.  
1974 }
1975
1976 % Some trouble maybe with hbox full, so we try optional word breaks.
1977 A debugging
1978 information entry may have a 
1979 \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name}
1980 attribute
1981 whose value is a null-terminated string describing the object
1982 file linkage name associated with the corresponding entity.
1983
1984 % Some trouble here with hbox full, so we try optional word breaks.
1985 \textit{Debugging information entries to which \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name}
1986 may apply include: \livelink{chap:DWTAGcommonblock}{DW\-\_TAG\-\_common\-\_block}, \livelink{chap:DWTAGconstant}{DW\-\_TAG\-\_constant},
1987 \livelink{chap:DWTAGentrypoint}{DW\-\_TAG\-\_entry\-\_point}, \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} 
1988 and \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}.
1989 }