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