4c6d9e7a9eee9cce0bbbcf68ddbf648fffc85e90
[dwarf-doc.git] / dwarf5 / latexdoc / otherdebugginginformation.tex
1 \chapter{Other Debugging Information}
2 \label{chap:otherdebugginginformation}
3 % references to chapter 7 look like  {datarep:...}
4 This section describes debugging information that is not
5 represented in the form of debugging information entries and
6 is not contained within a \dotdebuginfo{} section.
7
8 In the descriptions that follow, these terms are used to
9 specify the representation of DWARF sections:
10 \begin{itemize}
11 \item
12 \HFTinitiallength{}, \HFTsectionoffset{} and 
13 \HFTsectionlength{}, which are
14 defined in 
15 Sections \refersec{datarep:initiallengthvalues} and 
16 \refersec{datarep:32bitand64bitdwarfformats}.
17 \item
18 \HFTsbyte{}, 
19 \HFTubyte{}, 
20 \HFTuhalf{} and 
21 \HFTuword{}, 
22 which are defined in 
23 Section \refersec{datarep:integerrepresentationnames}.
24 \end{itemize}
25
26 \section{Accelerated Access}
27 \label{chap:acceleratedaccess}
28
29 \textit{A debugger frequently needs to find the debugging information
30 \addtoindexx{accelerated access}
31 for a program entity defined outside of the compilation unit
32 where the debugged program is currently stopped. Sometimes the
33 debugger will know only the name of the entity; sometimes only
34 the address. To find the debugging information associated with
35 a global entity by name, using the DWARF debugging information
36 entries alone, a debugger would need to run through all
37 entries at the highest scope within each compilation unit.}
38
39 \textit{Similarly, in languages in which the name of a type is
40 required to always refer to the same concrete type (such as
41 C++), a compiler may choose to elide type definitions in
42 all compilation units except one. In this case a debugger
43 needs a rapid way of locating the concrete type definition
44 by name. As with the definition of global data objects, this
45 would require a search of all the top level type definitions
46 of all compilation units in a program.}
47
48 \needlines{4}
49 \textit{To find the debugging information associated with a subroutine,
50 given an address, a debugger can use the low and high PC
51 attributes of the compilation unit entries to quickly narrow
52 down the search, but these attributes only cover the range
53 of addresses for the text associated with a compilation unit
54 entry. To find the debugging information associated with a
55 data object, given an address, an exhaustive search would be
56 needed. Furthermore, any search through debugging information
57 entries for different compilation units within a large program
58 would potentially require the access of many memory pages,
59 probably hurting debugger performance.}
60
61 To make lookups of program entities (including data objects, 
62 functions and types) by name or by address faster, a producer 
63 of DWARF information may provide two different types of tables
64 containing information about the debugging information
65 entries owned by a particular compilation unit entry in a
66 more condensed format.
67
68 \subsection{Lookup by Name}
69 \addtoindexx{lookup!by name}
70 \addtoindexx{accelerated access!by name}
71 For lookup by name, a name index is maintained in a separate
72 object file section named \dotdebugnames{}. 
73
74 \textit{The \dotdebugnames{} section is new in \DWARFVersionV,
75 and supersedes the \dotdebugpubnames{} and \dotdebugpubtypes{}
76 sections of earlier DWARF versions. While \dotdebugnames{} and
77 either \dotdebugpubnames{} and/or \dotdebugpubtypes{} sections
78 cannot both occur in the same compilation unit, both may be
79 found in the set of units that make up an executable or shared
80 object.}
81
82 The index consists
83 primarily of two parts: a list of names, and a list of index
84 entries. A name, such as a subprogram name, type name, or
85 variable name, may have several defining declarations in the
86 debugging information. In this case, the entry for that name in
87 the list of names will refer to a sequence of index entries in
88 the second part of the table, each corresponding to one defining
89 declaration in the \dotdebuginfo{} section.
90
91 The name index may also contain an optional hash table for faster
92 lookup.
93
94 A relocatable object file may contain a "per-CU" index, which
95 provides an index to the names defined in that compilation
96 unit.
97
98 An executable or shareable object file may contain either a collection of
99 "per-CU" indexes, simply copied from each relocatable object
100 file, or the linker may produce a "per-module" index by
101 combining the per-CU indexes into a single index that covers
102 the entire load module.
103
104 \subsubsection{Contents of the Name Index}
105 \label{chap:contentsofthenameindex}
106 The name index must contain an entry for each 
107 debugging information entry that defines a
108 named subprogram, label, variable, type, or namespace, 
109 subject to the following rules:
110 \begin{itemize}
111
112 \item All non-defining declarations (that is, 
113       debugging information entries with a
114       \DWATdeclaration{} attribute) are excluded.
115
116 \item \DWTAGnamespace{} debugging information entries 
117       without a \DWATname{} attribute are
118       included with the name 
119       \doublequote{\texttt{(anonymous namespace)}}.
120
121 \item All other debugging information entries 
122       without a \DWATname{} attribute are excluded.
123
124 \item \DWTAGsubprogram{}, \DWTAGinlinedsubroutine{}, and
125       \DWTAGlabel{} debugging information entries 
126       without an address attribute (\DWATlowpc{},
127       \DWAThighpc{}, \DWATranges{}, or \DWATentrypc{}) 
128       are excluded.
129
130 \item \DWTAGvariable{} debugging information entries 
131       with a \DWATlocation{} attribute that includes a 
132       \DWOPaddr{} or \DWOPformtlsaddress{} operator are
133       included; otherwise, they are excluded.
134
135 \item If a subprogram or inlined subroutine is included, and has a
136       \DWATlinkagename{} attribute, there will be an additional
137       index entry for the linkage name.
138       
139 \end{itemize}
140
141 For the purposes of determining whether a 
142 debugging information entry has a particular
143 attribute (such as \DWATname{}), if 
144 debugging information entry $A$ has a \DWATspecification{}
145 or \DWATabstractorigin{} attribute pointing to another 
146 debugging information entry $B$, any
147 attributes of $B$ are considered to be part of $A$.
148
149 \textit{The intent of the above rules is to provide the consumer with
150 some assurance that looking up an unqualified name in the index
151 will yield all relevant debugging information entries
152 that provide a defining declaration
153 at global scope for that name.}
154
155 \textit{A producer may choose to implement additional rules for what
156 names are placed in the index, and may communicate those rules to
157 a cooperating consumer via an augmentation string, described
158 below.}
159
160 \needlines{4}
161 \subsubsection{Structure of the Name Index}
162 \label{chap:structureofthenametindex}
163 Logically, the name index can be viewed as a list of names, 
164 with a list of index entries for each name. Each index entry 
165 corresponds to a debugging information entry 
166 that matches the criteria given in the previous section. For
167 example, if one compilation unit has a function named \texttt{fred} 
168 and another has a struct named \texttt{fred}, a lookup for 
169 \doublequote{fred} will find the list containing those two index 
170 entries.
171
172 The index section contains eight individual parts, as illustrated in 
173 Figure \referfol{fig:nameindexlayoutpart1}.
174 \begin{enumerate}
175 \item A header, describing the layout of the section.
176
177 \item A list of compile units (CUs) referenced by this index.
178
179 \item A list of local type units (TUs) referenced by this index
180     that are present in this object file.
181
182 \item A list of foreign type units (TUs) referenced by this index
183     that are not present in this object file (that is, that have
184     been placed in a \splitDWARFobjectfile{} as described in
185     \refersec{datarep:splitdwarfobjectfiles}).
186
187 \item An optional hash lookup table.
188
189 \item The name table.
190
191 \item An abbreviations table, similar to the one used by the
192     \dotdebuginfo{} section.
193
194 \item The entry pool, containing a list of index entries for each
195     name in the name list.
196 \end{enumerate}
197
198 \begin{figure}[p]
199 \figurepart{1}{2}
200 \begin{center}
201 %\includegraphics[keepaspectratio=true,scale=1.0]{name-index-drawings-6p1}
202
203 \begin{tikzpicture}[
204   every node/.style={node font=\small, anchor=north west, text height=.8em, text depth=.2em, inner sep=4pt, outer ysep=0},
205   caption/.style={node font=\small \bfseries, text width=90pt},
206   overview/.style={draw, node font=\small, minimum height=28pt, text width=80pt},
207   detail1/.style={draw, minimum height=14pt, text width=116pt},
208   detail2/.style={draw, minimum height=28pt, text width=116pt},
209   detail3/.style={draw, minimum height=48pt, text width=116pt},
210   detail4/.style={draw, minimum height=72pt, text width=116pt},
211   ellip/.style={draw, shape=broken rectangle, minimum height=14pt, text width=116pt},
212   explode/.style={draw=black!50, fill=black!20, line join=bevel},
213   header/.style={fill=headerblue},
214   culist/.style={fill=cutuyellow},
215   buckets/.style={fill=bucketsblue},
216   hashes/.style={fill=hashesgreen},
217   stroffsets/.style={fill=stroffsetspink},
218   entryoffsets/.style={fill=entryoffsetspink},
219   indexentries/.style={fill=indexentriesorange}
220 ]
221
222 % Name Table Overview
223
224 \begin{scope}[start chain=going below, node distance=0]
225   \node           [on chain,caption]  {Name Index};
226   \node (header)  [on chain,overview,header] {Header};
227   \node (culist)  [on chain,overview,header] {CU List};
228   \node (ltulist) [on chain,overview,header] {Local TU List};
229   \node (ftulist) [on chain,overview,header] {Foreign TU List};
230   \node (hash)    [on chain,overview,header] {Hash Table};
231   \node (names)   [on chain,overview,header] {Name Table};
232   \node (abbrev)  [on chain,overview,header] {Abbrev Table};
233   \node (pool)    [on chain,overview,header] {Entry Pool};
234 \end{scope}
235
236 % Exploded View of CU List
237
238 \begin{scope}[start chain=going below, node distance=0, shift={($(header.north east) + (72pt,18pt)$)}]
239   \node (cu0) [on chain,detail1,culist] {offset to CU 0};
240   \node (cu1) [on chain,detail1,culist] {offset to CU 1};
241   \node (cu2) [on chain,ellip,culist]   {\dots};
242   \node (cu3) [on chain,detail1,culist] {offset to CU $k - 1$};
243 \end{scope}
244
245 \begin{scope}[on background layer]
246   \filldraw [explode] (culist.north east) -- (cu0.north west) -- (cu3.south west) -- (culist.south east) -- cycle;
247 \end{scope}
248
249 \path [decoration={brace,amplitude=6pt}] ([xshift=9pt]cu0.north east)
250       [draw,decorate] -- ([xshift=9pt]cu3.south east)
251       node [midway,right,inner xsep=9pt] {\texttt{comp\_unit\_count} $(= k)$};
252
253 % Exploded View of Local TU List
254
255 \begin{scope}[start chain=going below, node distance=0, shift={($(cu3.south west) + (0,-9pt)$)}]
256   \node (ltu0) [on chain,detail1,culist] {offset to TU 0};
257   \node (ltu1) [on chain,detail1,culist] {offset to TU 1};
258   \node (ltu2) [on chain,ellip,culist]   {\dots};
259   \node (ltu3) [on chain,detail1,culist] {offset to TU $t - 1$};
260 \end{scope}
261
262 \begin{scope}[on background layer]
263   \filldraw [explode] (ltulist.north east) -- (ltu0.north west) -- (ltu3.south west) -- (ltulist.south east) -- cycle;
264 \end{scope}
265
266 \path [decoration={brace,amplitude=6pt}] ([xshift=9pt]ltu0.north east)
267       [draw,decorate] -- ([xshift=9pt]ltu3.south east)
268       node [midway,right,inner xsep=9pt] {\texttt{local\_type\_unit\_count} $(= t)$};
269
270 % Exploded View of Foreign TU List
271
272 \begin{scope}[start chain=going below, node distance=0, shift={($(ltu3.south west) + (0,-9pt)$)}]
273   \node (ftu0) [on chain,detail1,culist] {signature of TU $t$};
274   \node (ftu1) [on chain,detail1,culist] {signature of TU $t + 1$};
275   \node (ftu2) [on chain,ellip,culist]   {\dots};
276   \node (ftu3) [on chain,detail1,culist] {signature of TU $t + f - 1$};
277 \end{scope}
278
279 \begin{scope}[on background layer]
280   \filldraw [explode] (ftulist.north east) -- (ftu0.north west) -- (ftu3.south west) -- (ftulist.south east) -- cycle;
281 \end{scope}
282
283 \path [decoration={brace,amplitude=6pt}] ([xshift=9pt]ftu0.north east)
284       [draw,decorate] -- ([xshift=9pt]ftu3.south east)
285       node [midway,right,inner xsep=9pt] {\texttt{foreign\_type\_unit\_count} $(= f)$};
286
287 % Exploded View of Hash Table
288
289 \begin{scope}[start chain=going below, node distance=0, shift={($(ftu3.south west) + (0,-9pt)$)}]
290   \node (hash0) [on chain,detail2,buckets] {Buckets};
291   \node (hash1) [on chain,detail3,hashes]  {Hashes};
292 \end{scope}
293
294 \begin{scope}[on background layer]
295   \filldraw [explode] (hash.north east) -- (hash0.north west) -- (hash1.south west) -- (hash.south east) -- cycle;
296 \end{scope}
297
298 % Exploded View of Name Table
299
300 \begin{scope}[start chain=going below, node distance=0, shift={($(hash1.south west) + (0,-9pt)$)}]
301   \node (name0) [on chain,detail3,stroffsets]   {String Offsets};
302   \node (name1) [on chain,detail3,entryoffsets] {Entry Offsets};
303 \end{scope}
304
305 \begin{scope}[on background layer]
306   \filldraw [explode] (names.north east) -- (name0.north west) -- (name1.south west) -- (names.south east) -- cycle;
307 \end{scope}
308
309 % Exploded View of Entry Pool
310
311 \begin{scope}[shift={($(name1.south west) + (0,-9pt)$)}]
312   \node (pool0) [detail4,indexentries] {Index Entries};
313 \end{scope}
314
315 \begin{scope}[on background layer]
316   \filldraw [explode] (pool.north east) -- (pool0.north west) -- (pool0.south west) -- (pool.south east) -- cycle;
317 \end{scope}
318
319 %
320 \path [decoration={brace,amplitude=6pt}] ([xshift=9pt]hash0.north east)
321       [draw,decorate] -- ([xshift=9pt]pool0.south east)
322       node [midway,right,inner xsep=9pt] {\textit{see figure part 2 on next page}};
323
324 % Arrows pointing to .debug_info
325
326 \begin{scope}[shift={($(cu0.north east) + (15pt,27pt)$)}]
327   \node (debuginfo) {\textit{.debug\_info}};
328 \end{scope}
329
330 \path ([xshift=28pt]cu0.center) coordinate (p1);
331 \path ([xshift=14pt]p1) coordinate (c1);
332 \path ([yshift=2pt]debuginfo.west) coordinate (p2);
333 \path ([xshift=-14pt]p2) coordinate (c2);
334 \draw [dashed,{Circle[open]}-{Stealth[]}] (p1) .. controls (c1) and (c2) .. (p2);
335
336 \path ([xshift=28pt]ltu0.center) coordinate (p3);
337 \path ([xshift=60pt]p3) coordinate (c3);
338 \path ([yshift=-2pt]debuginfo.west) coordinate (p4);
339 \path ([shift={(-21pt,-7pt)}]p4) coordinate (c4);
340 \draw [dashed,{Circle[open]}-{Stealth[]}] (p3) .. controls (c3) and (c4) .. (p4);
341
342 \end{tikzpicture}
343
344 \caption{Name Index Layout}
345 \label{fig:nameindexlayoutpart1}
346 \end{center}
347 \end{figure}
348
349 \begin{figure}[p]
350 \figurepart{2}{2}
351 \begin{center}
352 %\includegraphics[keepaspectratio=true,scale=1.0]{name-index-drawings-6p2}
353
354 \begin{tikzpicture}[
355   every node/.style={node font=\small, anchor=north west, text height=.8em, text depth=.2em, inner sep=4pt, outer ysep=0},
356   % This diagram has a couple of two-line captions, so set the text depth
357   % to make room for the second line.
358   caption1/.style={node font=\small \bfseries, text depth=1.2em, text width=90pt},
359   caption2/.style={node font=\small \bfseries, text depth=1.2em, text width=41pt},
360   detail1/.style={draw, minimum height=14pt, text width=90pt},
361   detail2/.style={draw, minimum height=14pt, text width=41pt},
362   ellip1/.style={draw, shape=broken rectangle, minimum height=14pt, text width=90pt},
363   ellip2/.style={draw, shape=broken rectangle, minimum height=14pt, text width=41pt},
364   buckets/.style={fill=bucketsblue},
365   hashes/.style={fill=hashesgreen},
366   stroffsets/.style={fill=stroffsetspink},
367   entryoffsets/.style={fill=entryoffsetspink}
368 ]
369
370 % Buckets
371
372 \begin{scope}[start chain=going below, node distance=0]
373   \node           [on chain,caption1]        {\\ Buckets};
374   \node (bucket0) [on chain,detail1,buckets] {bucket 0};
375   \node (bucket1) [on chain,detail1,buckets] {bucket 1};
376   \node (bucket2) [on chain,ellip1,buckets]  {\dots};
377   \node (bucket3) [on chain,detail1,buckets] {bucket $b - 1$};
378 \end{scope}
379
380 \path [decoration={brace,amplitude=6pt}] ([xshift=40pt]bucket0.north east)
381       [draw,decorate] -- ([xshift=40pt]bucket3.south east)
382       node [midway,right,inner xsep=9pt] {\texttt{bucket\_count} $(= b)$};
383
384 % Hashes
385
386 \begin{scope}[start chain=going below, node distance=0, shift={($(bucket3.south east) + (18pt,-24pt)$)}]
387   \node (hashes) [on chain,caption1]       {\\ Hashes};
388   \node (hash0)  [on chain,detail1,hashes] {hash value 1};
389   \node (hash1)  [on chain,detail1,hashes] {hash value 2};
390   \node (hash2)  [on chain,detail1,hashes] {hash value 3};
391   \node (hash3)  [on chain,detail1,hashes] {hash value 4};
392   \node (hash4)  [on chain,detail1,hashes] {hash value 5};
393   \node (hash5)  [on chain,ellip1,hashes]  {\dots};
394   \node (hash6)  [on chain,detail1,hashes] {hash value $n$};
395 \end{scope}
396
397 % String Offsets
398
399 \begin{scope}[start chain=going below, node distance=0, shift={($(hashes.north east)$)}]
400   \node (strs) [on chain,caption2]           {String \\ Offsets};
401   \node (str0) [on chain,detail2,stroffsets] {};
402   \node (str1) [on chain,detail2,stroffsets] {};
403   \node (str2) [on chain,detail2,stroffsets] {};
404   \node (str3) [on chain,detail2,stroffsets] {};
405   \node (str4) [on chain,detail2,stroffsets] {};
406   \node (str5) [on chain,ellip2,stroffsets]  {};
407   \node (str6) [on chain,detail2,stroffsets] {};
408 \end{scope}
409
410 % Entry Offsets
411
412 \begin{scope}[start chain=going below, node distance=0, shift={($(strs.north east)$)}]
413   \node (entries) [on chain,caption2]             {Entry \\ Offsets};
414   \node (entry0)  [on chain,detail2,entryoffsets] {};
415   \node (entry1)  [on chain,detail2,entryoffsets] {};
416   \node (entry2)  [on chain,detail2,entryoffsets] {};
417   \node (entry3)  [on chain,detail2,entryoffsets] {};
418   \node (entry4)  [on chain,detail2,entryoffsets] {};
419   \node (entry5)  [on chain,ellip2,entryoffsets]  {};
420   \node (entry6)  [on chain,detail2,entryoffsets] {};
421 \end{scope}
422
423 \path [decoration={brace,amplitude=6pt}] ([xshift=9pt]entry0.north east)
424       [draw,decorate] -- ([xshift=9pt]entry6.south east)
425       node [midway,right,inner xsep=9pt] {\begin{tabular}{c} 
426                                           \texttt{name\_count} \\ 
427                                                      $(= n)$ 
428                                           \end{tabular}};
429
430 % Arrows pointing to .debug_str and entry pool
431
432 \path (str0.center) coordinate (p1);
433 \path ([xshift=18pt]p1) coordinate (c1);
434 \path ([shift={(36pt,45pt)}]p1) coordinate (p2);
435 \path ([xshift=-18pt]p2) coordinate (c2);
436 \draw [dashed,{Circle[open]}-{Stealth[]}] (p1) .. controls (c1) and (c2) .. (p2) node [anchor=west] {$.debug\_str$};
437
438 \path (entry0.center) coordinate (p3);
439 \path ([xshift=18pt]p3) coordinate (c3);
440 \path ([shift={(36pt,27pt)}]p3) coordinate (p4);
441 \path ([xshift=-18pt]p4) coordinate (c4);
442 \draw [dashed,{Circle[open]}-{Stealth[]}] (p3) .. controls (c3) and (c4) .. (p4) node [anchor=west] {$entry\ pool$};
443
444 % Arrows from buckets to hashes
445
446 \path ([xshift=24pt]bucket0.center) coordinate (p5);
447 \path ([xshift=130pt]p5) coordinate (c5);
448 \path ([xshift=-70pt]hash0.west) coordinate (c6);
449 \draw [dashed,{Circle[open]}-{Stealth[]}] (p5) .. controls (c5) and (c6) .. (hash0.west);
450
451 \path ([xshift=24pt]bucket1.center) coordinate (p7);
452 \path ([xshift=120pt]p7) coordinate (c7);
453 \path ([xshift=-144pt]hash3.west) coordinate (c8);
454 \draw [dashed,{Circle[open]}-{Stealth[]}] (p7) .. controls (c7) and (c8) .. (hash3.west);
455
456 \end{tikzpicture}
457
458 \vspace{15mm}
459
460 %\includegraphics[keepaspectratio=true,scale=1.0]{name-index-drawings-6p3}
461 \begin{tikzpicture}[
462   every node/.style={node font=\small, anchor=north west, text height=.8em, text depth=.2em, inner sep=4pt, outer ysep=0},
463   caption/.style={node font=\small \bfseries, text width=120pt},
464   detail/.style={draw, node font=\small, minimum height=14pt, text width=120pt},
465   ellip/.style={draw, shape=broken rectangle, minimum height=14pt, text width=120pt},
466   explode/.style={draw=black!50, fill=black!20, line join=bevel},
467   indexentries/.style={fill=indexentriesorange}
468 ]
469
470 % Entry Pool
471
472 \begin{scope}[start chain=going below, node distance=0]
473   \node           [on chain,caption]             {Entry Pool};
474   \node (entry0)  [on chain,detail,indexentries] {index entry \#1 for ``a''};
475   \node (entry1)  [on chain,detail,indexentries] {index entry \#2 for ``a''};
476   \node (entry2)  [on chain,ellip,indexentries]  {\dots};
477   \node (entry3)  [on chain,detail,indexentries] {0 \textit{(end of entries for ``a'')}};
478   \node (entry4)  [on chain,detail,indexentries] {index entry \#1 for ``b''};
479   \node (entry5)  [on chain,detail,indexentries] {index entry \#2 for ``b''};
480   \node (entry6)  [on chain,ellip,indexentries]  {\dots};
481   \node (entry7)  [on chain,detail,indexentries] {0};
482   \node (entry8)  [on chain,detail,indexentries] {index entry \#1 for ``c''};
483   \node (entry9)  [on chain,ellip,indexentries]  {\dots};
484 \end{scope}
485
486 % Exploded Index Entry
487
488 \begin{scope}[start chain=going below, node distance=0, shift={($(entry1.north east) + (60pt,30pt)$)}]
489   \node (abbrev) [on chain,detail,indexentries] {abbrev code};
490   \node (attr1)  [on chain,detail,indexentries] {attribute};
491   \node (attr2)  [on chain,detail,indexentries] {attribute};
492   \node (attr3)  [on chain,ellip,indexentries]  {\dots};
493   \node (attr4)  [on chain,detail,indexentries] {attribute};
494 \end{scope}
495
496 \begin{scope}[on background layer]
497   \filldraw [explode] (entry1.north east) -- (abbrev.north west) -- (attr4.south west) -- (entry1.south east) -- cycle;
498 \end{scope}
499
500 % Arrows
501
502 \node (from1) [anchor=east] at ([xshift=-36pt]entry0.west) {\textit{(from name table)}};
503 \draw [dashed,-{Stealth[]}] (from1) -- (entry0.west);
504
505 \node (from2) [anchor=east] at ([xshift=-36pt]entry4.west) {\textit{(from name table)}};
506 \draw [dashed,-{Stealth[]}] (from2) -- (entry4.west);
507
508 \node (from2) [anchor=east] at ([xshift=-36pt]entry7.west) {\textit{(from name table)}};
509 \draw [dashed,-{Stealth[]}] (from2) -- (entry7.west);
510
511 \end{tikzpicture}
512
513 \vspace{3mm}
514 %\caption{Name Index Layout \textit{(concluded)}}
515 Figure~\ref{fig:nameindexlayoutpart1}: Name Index Layout \textit{(concluded)}
516 %\label{fig:nameindexlayoutpart2}
517 \end{center}
518 \end{figure}
519
520 The formats of the header and the hash lookup table are described
521 in Section \refersec{chap:datarepresentationofthenameindex}.
522
523 The list of CUs and the list of local TUs are each an array of
524 offsets, each of which is the offset of a compile unit or a type unit
525 in the \dotdebuginfo{} section. For a per-CU index, there is a single CU
526 entry, and there may be a TU entry for each type unit generated in the
527 same translation unit as the single CU. For a per-module index, there
528 will be one CU entry for each compile unit in the module, and one TU
529 entry for each unique type unit in the module. Each list is indexed
530 starting at 0.
531
532 The list of foreign TUs is an array of 64-bit (\DWFORMrefsigeight) type
533 signatures, representing types referenced by the index whose
534 definitions have been placed in a different object file (that is, a split
535 DWARF object). This list may be empty. 
536 The foreign TU list immediately follows the local TU list 
537 and they both use the same index, so that if there are $N$ local TU entries, 
538 the index for the first foreign TU is $N$.
539
540 The name table is logically a table with a row for each unique name in
541 the index, and two columns. The first column contains a reference to
542 the name, as a string. The second column contains the offset within
543 the entry pool of the list of index entries for the name.
544
545 \needlines{4}
546 The abbreviations table describes the formats of the entries in the
547 entry pool. Like the DWARF abbreviations table in the \dotdebugabbrev{}
548 section, it defines one or more abbreviation codes. Each abbreviation
549 code provides a DWARF tag value followed by a list of pairs that
550 defines an attribute and form code used by entries with that
551 abbreviation code.
552
553 The entry pool contains all the index entries, grouped by name. The
554 second column of the name list points to the first index entry for the
555 name, and all the index entries for that name are placed one after the
556 other.
557
558 Each index entry begins with an unsigned LEB128 abbreviation code.
559 The  abbreviation list for that code provides the DWARF tag value for
560 the entry as well as the set of attributes provided by the entry and
561 their forms.
562
563 \needlines{4}
564 The standard attributes are:
565 \begin{itemize}
566 \item Compilation Unit (CU), a reference to an entry in the list of
567     CUs. In a per-CU index, index entries without this attribute
568     implicitly refer to the single CU.
569
570 \item Type Unit (TU), a reference to an entry in the list of local
571     or foreign TUs.
572
573 \item Debugging information entry offset within the CU or TU.
574
575 \item Parent debugging information entry, 
576     a reference to the index entry for the parent.
577     This is represented as the offset of the entry relative to
578     the start of the entry pool.
579
580 \item Type hash, an 8-byte hash of the type declaration.
581
582 \end{itemize}
583
584 \needlines{6}
585 It is possible that an indexed debugging information entry
586 has a parent that is not
587 indexed (for example, if its parent does not have a name attribute). 
588 In such a case, a parent attribute may point to a nameless index
589 entry (that is, one that cannot be reached from any entry in the
590 name table), or it may point to the nearest ancestor that does
591 have an index entry.
592
593 A producer may define additional vendor-specific attributes, 
594 and a consumer will be able to ignore and skip over any attributes 
595 it is not prepared to handle.
596
597 \needlines{4}
598 When an index entry refers to a foreign type unit, it may have
599 attributes for both CU and (foreign) TU. For such entries, the CU
600 attribute gives the consumer a reference to the CU that may be used to
601 locate a \splitDWARFobjectfile{} that contains the type unit.
602
603 \textit{The type hash attribute, not to be confused with the type signature
604 for a TU, may be provided for type entries whose declarations are not
605 in a type unit, for the convenience of link-time or post-link
606 utilities that wish to de-duplicate type declarations across
607 compilation units. The type hash, however, is computed by the
608 same method as specified for type signatures.}
609
610 The last entry for each name is followed by a zero byte that
611 terminates the list. There may be gaps between the lists.
612
613 \subsubsection{Per-CU versus Per-Module Indexes}
614 \label{chap:percuvspermoduleindexes}
615 \textit{In a per-CU index, the CU list may have only a single entry, 
616 and index entries may omit the CU attribute. (Cross-module or link-time
617 optimization, however, may produce an object file with several compile
618 units in one object. A compiler in this case may produce a separate
619 index for each CU, or a combined index for all CUs. In the latter
620 case, index entries will require the CU attribute.) Most name table
621 entries may have only a single index entry for each, but sometimes a
622 name may be used in more than one context and will require multiple
623 index entries, each pointing to a different debugging information
624 entry.}
625
626 \textit{When linking object files containing per-CU indexes, the 
627 linker may choose to concatenate the indexes as ordinary sections, 
628 or it may choose to combine the input indexes into a single 
629 per-module index.}
630
631 \textit{A per-module index will contain a number of CUs, and each index 
632 entry contains a CU attribute or a TU attribute to identify which 
633 CU or TU contains the debugging information entry being indexed. When a
634 given name is used in multiple CUs or TUs, it will typically have a
635 series of index entries pointing to each CU or TU where it is declared. 
636 For example, an index entry for a \addtoindex{C++} namespace needs to
637 list each occurrence, since each CU may contribute additional names to
638 the namespace, and the consumer needs to find them all. On the
639 other hand, some index entries do not need to list more than one
640 definition; for example, with the one-definition rule in \addtoindex{C++},
641 duplicate entries for a function may be omitted, since the consumer
642 only needs to find one declaration. Likewise, a per-module index needs
643 to list only a single copy of a type declaration contained in a type
644 unit.}
645
646 \textit{For the benefit of link-time or post-link utilities that consume
647 per-CU indexes and produce a per-module index, the per-CU index
648 entries provide the tag encoding for the original debugging
649 information entry, and may provide a type hash for certain types that
650 may benefit from de-duplication. For example, the standard declaration
651 of the typedef \texttt{uint32\_t} is likely to occur in many CUs, but a
652 combined per-module index needs to retain only one; a user declaration
653 of a typedef \texttt{mytype} may refer to a different type at each
654 occurrence, and a combined per-module index retains each unique
655 declaration of that type.}
656
657
658 \subsubsection{Data Representation of the Name Index}
659 \label{chap:datarepresentationofthenameindex}
660 The name index is placed in a section named \dotdebugnames, and
661 consists of the eight parts described in the following sections.
662
663 \subsubsubsection{Section Header}
664 The section header contains the following fields:
665 \begin{enumerate}[1. ]
666 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
667 \addttindexx{unit\_length}
668 The length of this contribution to the name index section,
669 not including the length field itself.
670
671 \item \texttt{version} (\HFTuhalf) \\
672 A version number\addtoindexx{version number!name index table} 
673 (see Section \refersec{datarep:nameindextable}). 
674 This number is specific to the name index table and is
675 independent of the DWARF version number.
676
677 \item \textit{padding} (\HFTuhalf) \\
678 Reserved to DWARF (must be zero). 
679
680 \item \texttt{comp\_unit\_count} (\HFTuword) \\
681 The number of CUs in the CU list.
682
683 \item \texttt{local\_type\_unit\_count} (\HFTuword) \\
684 The number of TUs in the local TU list.
685
686 \item \texttt{foreign\_type\_unit\_count} (\HFTuword) \\
687 The number of TUs in the foreign TU list.
688
689 \item \texttt{bucket\_count} (\HFTuword) \\
690 The number of hash buckets in the hash lookup table. 
691 If there is no hash lookup table, this field contains 0.
692
693 \item \texttt{name\_count} (\HFTuword) \\
694 The number of unique names in the index.
695
696 \item \texttt{abbrev\_table\_size} (\HFTuword) \\
697 The size in bytes of the abbreviations table.
698
699 \item \texttt{augmentation\_string\_size} (\HFTuword) \\
700 The size in bytes of the augmentation string. This value is
701 rounded up to a multiple of 4.
702
703 \item \texttt{augmentation\_string} (\HFTaugstring) \\
704 A vendor-specific augmentation string, which provides additional 
705 information about the contents of this index. If provided, the string
706 begins with a 4-character vendor ID. The remainder of the
707 string is meant to be read by a cooperating consumer, and its
708 contents and interpretation are not specified here. The
709 string is padded with null characters to a multiple of
710 four bytes in length.
711
712 \textit{The presence of an unrecognised augmentation string may make it impossible
713 for a consumer to process data in the \dotdebugnames{} section.}
714
715 \end{enumerate}
716
717 \needlines{4}
718 \subsubsubsection{List of CUs}
719 The list of CUs immediately follows the header. Each entry in the 
720 list is an offset of the corresponding compilation unit
721 in the \dotdebuginfo{} section.
722 In the DWARF-32 format, a section offset is 4 bytes, 
723 while in the DWARF-64 format, a section offset is 8 bytes.
724
725 The total number of entries in the list is given by \texttt{comp\_unit\_count}.
726 There must be at least one CU.
727
728 \needlines{4}
729 \subsubsubsection{List of Local TUs}
730 The list of local TUs immediately follows the list of CUs. Each 
731 entry in the list is an offset of the corresponding type unit
732 in the \dotdebuginfo{} section. 
733 In the DWARF-32 format, a section offset is 4 bytes, 
734 while in the DWARF-64 format, a section offset is 8 bytes.
735
736 The total number of entries in the list is given by
737 \texttt{local\_type\_unit\_count}. This list may be empty.
738
739 \subsubsubsection{List of Foreign TUs}
740 The list of foreign TUs immediately follows the list of local TUs.
741 Each entry in the list is a 8-byte type signature (as described by
742 \DWFORMrefsigeight).
743
744 The number of entries in the list is given by \texttt{foreign\_type\_unit\_count}.
745 This list may be empty.
746
747 \needlines{4}
748 \subsubsubsection{Hash Lookup Table}
749 The optional hash lookup table immediately follows the list of type signatures.
750
751 The hash lookup table is actually two separate arrays: an array of
752 buckets, followed immediately by an array of hashes. The number of
753 entries in the buckets array is given by \texttt{bucket\_count}, and the number
754 of entries in the hashes array is given by \texttt{name\_count}. Each array
755 contains 4-byte unsigned integers.
756
757 \needlines{4}
758 Symbols are entered into the hash table by first computing a hash
759 value from the symbol name. The hash is computed 
760 using the "DJB" hash function\addtoindexx{DJB hash function} 
761 described in Section \refersec{datarep:nametablehashfunction}.
762 Given a hash value for the symbol,
763 the symbol is entered into a bucket whose index is the hash value
764 modulo \texttt{bucket\_count}. The buckets array is indexed starting at 0.
765
766 Each bucket contains the index of an entry in the hashes array. The
767 hashes array is indexed starting at 1, and an empty bucket is
768 represented by the value 0.
769
770 \needlines{4}
771 The hashes array contains a sequence of the full hash values for each
772 symbol. All symbols that have the same index into the bucket list 
773 follow one another in the hashes array, and the indexed entry in 
774 the bucket list refers to the first symbol. 
775 When searching for a symbol, the search 
776 starts at the index given by the bucket, and continues either until a
777 matching symbol is found or until a hash value from a different bucket
778 is found. If two different symbol names produce the same hash value,
779 that hash value will occur twice in the hashes array. Thus, if a
780 matching hash value is found, but the name does not match, the search
781 continues visiting subsequent entries in the hashes table.
782
783 When a matching hash value is found in the hashes array, the index of
784 that entry in the hashes array is used to find the corresponding entry
785 in the name table.
786
787 \needlines{6}
788 \subsubsubsection{Name Table}
789 The name table immediately follows the hash lookup table. The name
790 table is laid out in column-major order (that is, the first column,
791 followed by the second column). Each entry in the first column
792 contains the string table offset (\DWFORMstrp) of the name in the
793 \dotdebugstr{} (or \dotdebugstrdwo) section. Each entry in the second
794 column contains the offset (as a section offset) within the entry pool
795 of the list of index entries for the name. Rows in the name table are
796 indexed starting at 1 (to match the hashes array).
797
798 The number of rows in the name table is given by \texttt{name\_count}.
799
800 If there is a hash lookup table, the 
801 row number of an entry in the name table must
802 match the row number of its corresponding entry in the hashes array.
803
804 If there is no hash lookup table, there is no ordering 
805 requirement for the name table.
806
807 \needlines{6}
808 \subsubsubsection{Abbreviations Table}
809 The abbreviations table immediately follows the name table. This table
810 consists of a series of abbreviation declarations. Its size is given
811 by \texttt{abbrev\_table\_size}.
812
813 Each abbreviation declaration defines the tag and other attributes for
814 a particular form of index entry. Each declaration starts with an
815 unsigned LEB128 number representing the abbreviation code itself. It
816 is this code that appears at the beginning of an index entry. The
817 abbreviation code must not be 0.
818
819 The abbreviation code is followed by another unsigned LEB128 number
820 that encodes the tag of the debugging information entry corresponding
821 to the index entry.
822
823 Following the tag encoding is a series of attribute specifications.
824 Each attribute consists of two parts: an unsigned LEB128 number that
825 represents the index attribute, and another unsigned LEB128 number
826 that represents the attribute's form (as described in 
827 Section \refersec{datarep:attributeencodings}). The series of attribute 
828 specifications ends with an entry containing 0 for the attribute and 
829 0 for the form.
830
831 The index attributes and their meanings are listed in 
832 Table \referfol{tab:indexattributeencodings}.
833
834 \begin{centering}
835 \setlength{\extrarowheight}{0.1cm}
836 \begin{longtable}{l|l}
837   \caption{Index attribute encodings} \label{tab:indexattributeencodings}\\
838   \hline \bfseries Attribute name &\bfseries Meaning \\ \hline
839 \endfirsthead
840   \bfseries Attribute name &\bfseries Meaning \\ \hline
841 \endhead
842   \hline \emph{Continued on next page}
843 \endfoot
844   \hline
845 \endlastfoot
846 \DWIDXcompileunitTARG & Index of CU                                  \\
847 \DWIDXtypeunitTARG    & Index of TU (\mbox{local} or foreign)        \\
848 \DWIDXdieoffsetTARG   & Offset of DIE within CU or TU                \\
849 \DWIDXparentTARG      & Index of name \mbox{table} entry for parent  \\
850 \DWIDXtypehashTARG    & Hash of type \mbox{declaration}              \\
851 \end{longtable}
852 \end{centering}
853
854 The abbreviations table ends with an entry consisting of a single 0
855 byte for the abbreviation code. The size of the table given by
856 \texttt{abbrev\_table\_size} may include optional padding following the
857 terminating 0 byte.
858
859 \subsubsubsection{Entry Pool}
860 The entry pool immediately follows the abbreviations table. The second
861 column of each row of the name table points to an offset in the entry
862 pool, where a series of index entries for that name is located.
863
864 \needlines{4}
865 Each index entry in the series begins with an abbreviation code, and is
866 followed by the attributes described by the abbreviation declaration
867 for that code. The last index entry in the series is followed by a
868 terminating entry whose abbreviation code is 0.
869
870 Gaps are not allowed between entries in a series (that is, the entries
871 for a single name must all be contiguous), but there may be gaps
872 between series.
873
874 \textit{For example, a producer/consumer combination may find
875 it useful to maintain alignment.}
876
877 The size of the entry pool is the remaining size of the contribution to
878 the index section, as defined by the \texttt{unit\_length} header field.
879
880 \subsection{Lookup by Address}
881 \label{chap:lookupbyaddress}
882 For \addtoindexx{lookup!by address}
883 lookup by address, a table is maintained in a separate
884 \addtoindexx{accelerated access!by address}
885 object file section called 
886 \dotdebugaranges{}. The table consists
887 of sets of variable length entries, each set describing the
888 portion of the program\textquoteright{}s address space that is covered by
889 a single compilation unit.
890
891 \needlines{4}
892 Each set begins with a header containing five values:
893 \begin{enumerate}[1. ]
894 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
895 \addttindexx{unit\_length}
896 The length of this contribution to the address lookup section,
897 not including the length field itself.
898
899 \item \texttt{version} (\HFTuhalf) \\
900 A version number\addtoindexx{version number!address lookup table}
901 (see Section \refersec{datarep:addrssrangetable}). 
902 This number is specific to the address lookup table and is
903 independent of the DWARF version number.
904
905 \item \texttt{debug\_info\_offset} (section offset) \\
906 The offset from the
907 \addtoindexx{section offset!in .debug\_aranges header}
908 beginning of the \dotdebuginfo{} section of the
909 compilation unit header referenced by the set.
910
911 \item \texttt{address\_size} (\HFTubyte) \\
912 The \addtoindex{size of an address}
913 in bytes on
914 \addttindexx{address\_size}
915 the target architecture. For 
916 \addtoindexx{address space!segmented}
917 segmented addressing, this is
918 the size of the offset portion of the address.
919
920 \item \HFNsegmentselectorsize{} (\HFTubyte) \\
921 The size of a segment selector in
922 bytes on the target architecture. If the target system uses
923 a flat address space, this value is 0.
924
925 \end{enumerate}
926
927 This header is followed by a variable number of address range
928 descriptors. Each descriptor is a triple consisting of a
929 segment selector, the beginning address within that segment
930 of a range of text or data covered by some entry owned by
931 the corresponding compilation unit, followed by the non-zero
932 length of that range. A particular set is terminated by an
933 entry consisting of three zeroes. 
934 When the \HFNsegmentselectorsize{} value
935 is zero in the header, the segment selector is omitted so that
936 each descriptor is just a pair, including the terminating
937 entry. By scanning the table, a debugger can quickly decide
938 which compilation unit to look in to find the debugging
939 information for an object that has a given address.
940
941 \textit{If the range of addresses covered by the text and/or data
942 of a compilation unit is not contiguous, then there may be
943 multiple address range descriptors for that compilation unit.}
944
945
946 \section{Line Number Information}
947 \label{chap:linenumberinformation}
948 \textit{A source\dash level debugger needs to know how to
949 \addtoindexx{line number information|see{\textit{also} statement list attribute}}
950 associate locations in the source files with the corresponding
951 machine instruction addresses in the executable or the shared 
952 object files used by that executable object file. Such an
953 association makes it possible for the debugger user
954 to specify machine instruction addresses in terms of source
955 locations. This is done by specifying the line number
956 and the source file containing the statement. The debugger
957 can also use this information to display locations in terms
958 of the source files and to single step from line to line,
959 or statement to statement.}
960
961 Line number information generated for a compilation unit is
962 represented in the 
963 \dotdebugline{} section of an object file, and optionally
964 also in the \dotdebuglinestr{} section, and
965 is referenced by a corresponding compilation unit debugging
966 information entry 
967 (see Section \refersec{chap:fullandpartialcompilationunitentries}) 
968 in the \dotdebuginfo{} section.
969
970 \textit{Some computer architectures employ more than one instruction
971 set (for example, the ARM 
972 \addtoindexx{ARM instruction set architecture}
973 and 
974 MIPS architectures support
975 \addtoindexx{MIPS instruction set architecture}
976 a 32-bit as well as a 16-bit instruction set). Because the
977 instruction set is a function of the program counter, it is
978 convenient to encode the applicable instruction set in the
979 \dotdebugline{} section as well.}
980
981 \textit{If space were not a consideration, the information provided
982 in the \dotdebugline{} 
983 section could be represented as a large
984 matrix, with one row for each instruction in the emitted
985 object code. The matrix would have columns for:}
986 \begin{itemize}
987 \item \textit{the source file name}
988 \item \textit{the source line number}
989 \item \textit{the source column number}
990 \item \textit{whether this instruction is the beginning of a source statement}
991 \item \textit{whether this instruction is the beginning of a \addtoindex{basic block}}
992 \item \textit{and so on}
993 \end{itemize}
994 \textit{Such a matrix, however, would be impractically large. We
995 shrink it with two techniques. First, we delete from
996 the matrix each row whose file, line, source column and
997 discriminator\addttindexx{discriminator} 
998 is identical with that of its
999 predecessors. Any deleted row would never be the beginning of
1000 a source statement. Second, we design a byte-coded language
1001 for a state machine and store a stream of bytes in the object
1002 file instead of the matrix. This language can be much more
1003 compact than the matrix. To the line number information a 
1004 consumer must \doublequote{run} the state machine
1005 to generate the matrix for each compilation unit of interest.
1006 The concept of an encoded matrix also leaves
1007 room for expansion. In the future, columns can be added to the
1008 matrix to encode other things that are related to individual
1009 instruction addresses.}
1010
1011 \needlines{10}
1012 \subsection{Definitions}
1013 \label{chap:definitions}
1014 The following terms are used in the description of the line
1015 number information format:
1016
1017 \begin{longtable} {lP{9cm}}
1018 state machine &
1019 The hypothetical machine used by a consumer of the line number
1020 information to expand the byte\dash coded 
1021 instruction stream into a matrix of
1022 line number information. \\
1023
1024 line number program &
1025 A series of byte\dash coded 
1026 line number information instructions representing
1027 one compilation unit. \\
1028
1029 \addtoindex{basic block} &
1030  A sequence of instructions where only the first instruction may be a
1031 branch target and only the last instruction may transfer control. A
1032 subprogram invocation is defined to be an exit from a 
1033 \addtoindex{basic block}.
1034
1035 \textit{A \addtoindex{basic block} does not 
1036 necessarily correspond to a specific source code
1037 construct.} \\
1038
1039 sequence &
1040 A series of contiguous target machine instructions. One compilation unit
1041 may emit multiple sequences (that is, not all instructions within a
1042 compilation unit are assumed to be contiguous). \\
1043 \end{longtable}
1044
1045 \needlines{8}
1046 \subsection{State Machine Registers}
1047 \label{chap:statemachineregisters}
1048 The line number information state machine has a number of  
1049 registers as shown in Table \referfol{tab:statemachineregisters}.
1050
1051 \begin{longtable}{l|P{9cm}}
1052   \caption{State machine registers } \label{tab:statemachineregisters} \\
1053   \hline \bfseries Register name&\bfseries Meaning\\ \hline
1054 \endfirsthead
1055   \bfseries Register name&\bfseries Meaning\\ \hline
1056 \endhead
1057   \hline \emph{Continued on next page}
1058 \endfoot
1059   \hline
1060 \endlastfoot
1061 \addtoindexi{\texttt{address}}{address register!in line number machine}&
1062 The program\dash counter value corresponding to a machine instruction
1063 generated by the compiler. \\
1064
1065 \addttindex{op\_index} &
1066 An unsigned integer representing the index of an operation within a VLIW
1067 instruction. The index of the first operation is 0. For non-VLIW
1068 architectures, this register will always be 0.  \\
1069
1070 \addttindex{file} &
1071 An unsigned integer indicating the identity of the source file
1072 corresponding to a machine instruction. \\
1073
1074 \addttindex{line} &
1075 An unsigned integer indicating a source line number. Lines are numbered
1076 beginning at 1. The compiler may emit the value 0 in cases where an
1077 instruction cannot be attributed to any source line. \\
1078
1079 \addttindex{column} &
1080 An unsigned integer indicating a column number within a source line.
1081 Columns are numbered beginning at 1. The value 0 is reserved to indicate
1082 that a statement begins at the \doublequote{left edge} of the line. \\
1083
1084 \addttindex{is\_stmt} &
1085 A boolean indicating that the current instruction is a recommended
1086 breakpoint location. A recommended breakpoint location 
1087 is intended to \doublequote{represent} a line, a 
1088 statement and/or a semantically distinct subpart of a
1089 statement. \\
1090
1091 \addttindex{basic\_block}  &
1092 A boolean indicating that the current instruction is the beginning of a
1093 \addtoindex{basic block}. \\
1094
1095 \addttindex{end\_sequence} &
1096 A boolean indicating that the current address is that of the first byte after
1097 the end of a sequence of target machine instructions. 
1098 \addttindex{end\_sequence}
1099 terminates a sequence of lines; therefore other information in the same
1100 row is not meaningful. \\
1101
1102 \addttindex{prologue\_end} &
1103 A boolean indicating that the current address is one (of possibly many)
1104 where execution should be suspended for a breakpoint at the entry of a
1105 function. \\
1106
1107 \addttindex{epilogue\_begin} &
1108 A boolean indicating that the current address is one (of possibly many)
1109 where execution should be suspended for a breakpoint just prior to
1110 the exit of a function. \\
1111
1112 \addttindex{isa} &
1113 An unsigned integer whose value encodes the applicable
1114 instruction set architecture for the current instruction.
1115
1116 \textit{The encoding of instruction sets should be shared by all
1117 users of a given architecture. It is recommended that this
1118 encoding be defined by the ABI authoring committee for each
1119 architecture.} \\
1120
1121 \addttindex{discriminator} &
1122 An unsigned integer identifying the block to which the
1123 current instruction belongs. Discriminator values are assigned
1124 arbitrarily by the DWARF producer and serve to distinguish
1125 among multiple blocks that may all be associated with the
1126 same source file, line, and column. Where only one block
1127 exists for a given source position, the discriminator value
1128 is be zero. \\
1129 \end{longtable}
1130
1131 The \texttt{address} and \addttindex{op\_index} registers,
1132 taken together, form an \addtoindex{operation pointer} that can 
1133 reference any individual operation within the instruction stream.
1134
1135 At the beginning  of each sequence within a line number
1136 program, the state of the registers is as show in Table
1137 \refersec{tab:linenumberprograminitiastate}.
1138 \begin{table}
1139 \caption{Line number program initial state}
1140 \label{tab:linenumberprograminitiastate}
1141 \begin{center}
1142 \begin{tabular}{l|p{9.5cm}}
1143 \hline
1144 \texttt{address} & 0 \\
1145 \addttindex{op\_index} & 0 \\
1146 \texttt{file} & 1 \\
1147 \texttt{line} & 1 \\
1148 \texttt{column} & 0 \\
1149 \addttindex{is\_stmt} & determined by \addttindex{default\_is\_stmt} 
1150                         in the line number program header \\
1151 \addttindex{basic\_block}    & \doublequote{false} \addtoindexx{basic block} \\
1152 \addttindex{end\_sequence}   & \doublequote{false} \\
1153 \addttindex{prologue\_end}   & \doublequote{false} \\
1154 \addttindex{epilogue\_begin} & \doublequote{false} \\
1155 \addttindex{isa} & 0 \\
1156 \addttindex{discriminator} & 0 \\
1157 \hline
1158 \end{tabular}
1159 \end{center}
1160 \vspace{5mm}
1161 \end{table}
1162
1163 \textit{The 
1164 \addttindex{isa} value 0 specifies that the instruction set is the
1165 architecturally determined default instruction set. This may
1166 be fixed by the ABI, or it may be specified by other means,
1167 for example, by the object file description.}
1168
1169 \needlines{6}
1170 \subsection{Line Number Program Instructions}
1171 The state machine instructions in a line number program belong to one of three categories:
1172
1173 \begin{enumerate}[1. ]
1174 \item special opcodes \\
1175 These have a \HFTubyte{} opcode field and no operands.\vspace{1ex}
1176
1177 \textit{Most of the instructions in a 
1178 line number program are special opcodes.}
1179
1180 \needlines{4}
1181 \item standard opcodes \\
1182 These have a \HFTubyte{} opcode field which may be followed by zero or more
1183 \addtoindex{LEB128} operands (except for 
1184 \mbox{\DWLNSfixedadvancepc,} see 
1185 Section \refersec{chap:standardopcodes}).
1186 The opcode implies the number of operands and their meanings, but the
1187 line number program header also specifies the number of operands for
1188 each standard opcode.
1189
1190 \needlines{4}
1191 \item extended opcodes \\
1192 These have a multiple byte format. The first byte is zero; the next bytes
1193 are an unsigned LEB128\addtoindexx{LEB128!unsigned} integer giving the number of bytes in the
1194 instruction itself (does not include the first zero byte or the size). The
1195 remaining bytes are the instruction itself (which begins with a \HFTubyte{}
1196 extended opcode). \\
1197 \end{enumerate}
1198
1199
1200 \subsection{The Line Number Program Header}
1201 \label{chap:linenumberprogramheader}
1202 The optimal encoding of line number information depends to a
1203 certain degree upon the architecture of the target machine. The
1204 line number program header provides information used by
1205 consumers in decoding the line number program instructions for
1206 a particular compilation unit and also provides information
1207 used throughout the rest of the line number program.
1208
1209 The line number program for each compilation unit begins with
1210 a header containing the following fields in order:
1211
1212 \begin{enumerate}[1. ]
1213 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length})  \\
1214 \addttindexx{unit\_length}
1215 The size in bytes of the line number information for this
1216 compilation unit, not including the length field itself
1217 (see Section \refersec{datarep:initiallengthvalues}). 
1218
1219 \needlines{4}
1220 \item \texttt{version} (\HFTuhalf) \\
1221 A version number\addtoindexx{version number!line number information} 
1222 (see Section \refersec{datarep:linenumberinformation}). 
1223 This number is specific to
1224 the line number information and is independent of the DWARF
1225 version number. 
1226
1227 \item \texttt{address\_size} (\HFTubyte)\\
1228 A 1-byte unsigned integer containing the size in bytes of an
1229 address (or offset portion of an address for segmented addressing)
1230 on the target system.
1231    
1232 \textit{The \addttindex{address\_size} field is new in DWARF Version 5. 
1233 It is needed to support the common practice of stripping all but 
1234 the line number sections (\dotdebugline{} and \dotdebuglinestr{}) 
1235 from an executable.}
1236
1237 \item \HFNsegmentselectorsize{} (\HFTubyte) \\
1238 A 1-byte unsigned integer containing the size in bytes of a segment
1239 selector on the target system.
1240    
1241 \textit{The \HFNsegmentselectorsize{} field is new in DWARF Version 5. 
1242 It is needed in combination with the \addttindex{address\_size} field 
1243 to accurately characterize the address representation on the target 
1244 system.}
1245
1246 \needlines{4}
1247 \item \texttt{header\_length}  \\
1248 The number of bytes following the \addttindex{header\_length} field to the
1249 beginning of the first byte of the line number program itself.
1250 In the \thirtytwobitdwarfformat, this is a 4-byte unsigned
1251 length; in the \sixtyfourbitdwarfformat, this field is an
1252 8-byte unsigned length 
1253 (see Section \refersec{datarep:32bitand64bitdwarfformats}). 
1254
1255 \item \texttt{minimum\_instruction\_length} (\HFTubyte)  \\
1256 \addttindexx{minimum\_instruction\_length}
1257 The size in bytes of the smallest target machine
1258 instruction. Line number program opcodes that alter
1259 the \texttt{address} and \addttindex{op\_index}
1260 registers use this and
1261 \addttindex{maximum\_operations\_per\_instruction}
1262 in their calculations. 
1263
1264 \needlines{9}
1265 \item \texttt{maximum\_operations\_per\_instruction} (\HFTubyte) \\
1266 The 
1267 \addttindexx{maximum\_operations\_per\_instruction}
1268 maximum number of individual operations that may be
1269 encoded in an instruction. Line number program opcodes
1270 that alter the \texttt{address} and 
1271 \addttindex{op\_index} registers use this and
1272 \addttindex{minimum\_instruction\_length} in their calculations.
1273
1274 For non-VLIW
1275 architectures, this field is 1, the \addttindex{op\_index} register is always
1276 0, and the \addtoindex{operation pointer} is simply the \texttt{address} register.
1277
1278 \needlines{4}
1279 \item \texttt{default\_is\_stmt} (\HFTubyte) \\
1280 \addttindexx{default\_is\_stmt}
1281 The initial value of the \addttindex{is\_stmt} register.  
1282
1283 \textit{A simple approach
1284 to building line number information when machine instructions
1285 are emitted in an order corresponding to the source program
1286 is to set \addttindex{default\_is\_stmt}
1287 to \doublequote{true} and to not change the
1288 value of the \addttindex{is\_stmt} register 
1289 within the line number program.
1290 One matrix entry is produced for each line that has code
1291 generated for it. The effect is that every entry in the
1292 matrix recommends the beginning of each represented line as
1293 a breakpoint location. This is the traditional practice for
1294 unoptimized code.}
1295
1296 \textit{A more sophisticated approach might involve multiple entries in
1297 the matrix for a line number; in this case, at least one entry
1298 (often but not necessarily only one) specifies a recommended
1299 breakpoint location for the line number. \DWLNSnegatestmt{}
1300 opcodes in the line number program control which matrix entries
1301 constitute such a recommendation and 
1302 \addttindex{default\_is\_stmt} might
1303 be either \doublequote{true} or \doublequote{false.} This approach might be
1304 used as part of support for debugging optimized code.}
1305
1306 \item \texttt{line\_base} (\HFTsbyte) \\
1307 \addttindexx{line\_base}
1308 This parameter affects the meaning of the special opcodes. See below.
1309
1310 \item \texttt{line\_range} (\HFTubyte) \\
1311 \addttindexx{line\_range}
1312 This parameter affects the meaning of the special opcodes. See below.
1313
1314 \needlines{4}
1315 \item \texttt{opcode\_base} (\HFTubyte) \\
1316 The 
1317 \addttindexx{opcode\_base}
1318 number assigned to the first special opcode.
1319
1320 \textit{Opcode base is typically one greater than the highest-numbered
1321 \addttindexx{opcode\_base}
1322 standard opcode defined for the specified version of the line
1323 number information (12 in DWARF Versions 3, 4 and 5,
1324 \addtoindexx{DWARF Version 3}
1325 \addtoindexx{DWARF Version 4}
1326 \addtoindexx{DWARF Version 5}
1327 and 9 in
1328 \addtoindexx{DWARF Version 2}
1329 Version 2).  
1330 If opcode\_base is less than the typical value,
1331 \addttindexx{opcode\_base}
1332 then standard opcode numbers greater than or equal to the
1333 opcode base are not used in the line number table of this unit
1334 (and the codes are treated as special opcodes). If \texttt{opcode\_base}
1335 is greater than the typical value, then the numbers between
1336 that of the highest standard opcode and the first special
1337 opcode (not inclusive) are used for vendor specific extensions.}
1338
1339 \needlines{4}
1340 \item \texttt{standard\_opcode\_lengths} (array of \HFTubyte) \\
1341 \addttindexx{standard\_opcode\_lengths}
1342 This array specifies the number of \addtoindex{LEB128} operands for each
1343 of the standard opcodes. The first element of the array
1344 corresponds to the opcode whose value is 1, and the last
1345 element corresponds to the opcode whose value 
1346 is \texttt{opcode\_base - 1}.
1347
1348 \textit{By increasing \texttt{opcode\_base}, and adding elements to this array,
1349 \addttindexx{opcode\_base}
1350 new standard opcodes can be added, while allowing consumers who
1351 do not know about these new opcodes to be able to skip them.}
1352
1353 \textit{Codes for vendor specific extensions, if any, are described
1354 just like standard opcodes.}
1355
1356 %%% Save the current enum counter so we can restart later
1357 %%% End this enumeration so the following text is outdented to
1358 %%% the left margin (because it applies to the many following
1359 %%% items
1360 \newcounter{saveenumi}
1361 \setcounter{saveenumi}{\value{enumi}}
1362 \end{enumerate}
1363
1364 \needlines{6}
1365 \textit{The remaining fields provide information about the
1366 source files used in the compilation. These fields
1367 have been revised in \DWARFVersionV{} to support these
1368 goals:}
1369 \begin{itemize}
1370 \item
1371     \textit{To allow new alternative means for a consumer to
1372     check that a file it can access is the same version
1373     as that used in the compilation.}
1374 \item
1375     \textit{To allow a producer to collect file name strings
1376     in a new section (\dotdebuglinestr{}) that can be used
1377     to merge duplicate file name strings.}
1378 \item
1379     \textit{To add the ability for producers to provide 
1380     vendor-defined information that can be skipped by a consumer
1381     that is unprepared to process it.}
1382 \end{itemize}
1383
1384 \begin{enumerate}[1. ]
1385 %%% Resume enumeration count where it left off above
1386 \setcounter{enumi}{\value{saveenumi}}
1387 \item \texttt{directory\_entry\_format\_count} (\HFTubyte) \\
1388 \addttindexx{directory\_entry\_format\_count}
1389     A count of the number of entries that occur in the
1390     following \addttindex{directory\_entry\_format} field.
1391
1392 \needlines{8}
1393 \item \texttt{directory\_entry\_format} (sequence of ULEB128 pairs) \\
1394 \addttindexx{directory\_entry\_format}
1395     A sequence of directory entry format descriptions.
1396     Each description consists of a pair of ULEB128 values:
1397 \begin{itemize}
1398 \setlength{\itemsep}{0em}
1399 \item A content type code (see 
1400 Sections \refersec{chap:standardcontentdescriptions} and
1401 \refersec{chap:vendordefinedcontentdescriptions}).
1402
1403 \item A form code using the attribute form codes
1404 \end{itemize}
1405
1406 \needlines{4} 
1407 \item \texttt{directories\_count} (ULEB128) \\
1408 \addttindexx{directories\_count}
1409 A count of the number of entries that occur in the
1410 following directories field.
1411
1412 \needlines{4}    
1413 \item \texttt{directories} (sequence of directory names) \\
1414 \addttindexx{directories}
1415 A sequence of directory names and optional related
1416 information. Each entry is encoded as described
1417 by the \addttindex{directory\_entry\_format} field.
1418    
1419 Entries in this sequence describe each path that was
1420 searched for included source files in this compilation,
1421 including the compilation directory of the compilation.
1422 (The paths include those directories specified by the
1423 user for the compiler to search and those the compiler
1424 searches without explicit direction.)
1425    
1426 The first entry is the current directory of the compilation.
1427 Each additional path entry is either a full path name or
1428 is relative to the current directory of the compilation.
1429    
1430 The line number program assigns a number (index) to each
1431 of the directory entries in order, beginning with 0.
1432    
1433 \textit{Prior to \DWARFVersionV, the current directory was not
1434 represented in the directories field and a directory index
1435 of 0 implicitly referred to that directory as found in the
1436 \DWATcompdir{} attribute of the compilation unit 
1437 debugging information entry. 
1438 In \DWARFVersionV, the current directory is explicitly present
1439 in the directories field. This is needed to support the
1440 common practice of stripping all but the line number sections
1441 (\dotdebugline{} and \dotdebuglinestr) from an executable.}
1442
1443 \textit{Note that if a \dotdebuglinestr{} section is present, 
1444 both the compilation unit debugging information entry 
1445 and the line number header can
1446 share a single copy of the current directory name string.}
1447
1448 \item \texttt{file\_name\_entry\_format\_count} (\HFTubyte) \\
1449 \addttindexx{file\_name\_entry\_format\_count}
1450 A count of the number of file entry format entries that
1451 occur in the following \addttindex{file\_name\_entry\_format} field. 
1452 If this field is zero, then the \addttindex{file\_names\_count} field 
1453 (see below) must also be zero.
1454
1455 \needlines{6}
1456 \item \texttt{file\_name\_entry\_format} (sequence of ULEB128 pairs) \\
1457 \addttindexx{file\_name\_entry\_format}
1458 A sequence of file entry format descriptions.
1459 Each description consists of a pair of ULEB128 values:
1460 \begin{itemize}
1461 \setlength{\itemsep}{0em}
1462 \item A content type code (see below)
1463 \item A form code using the attribute form codes
1464 \end{itemize}
1465
1466 \item \texttt{file\_names\_count} (ULEB128) \\
1467 \addttindexx{file\_names\_count}
1468 A count of the number of file name entries that occur
1469 in the following \addttindex{file\_names} field.
1470
1471 \needlines{4}
1472 \item \texttt{file\_names} (sequence of file name entries) \\
1473 \addttindexx{file\_names}
1474 A sequence of file names and optional related
1475 information. Each entry is encoded as described
1476 by the \addttindex{file\_name\_entry\_format} field.
1477   
1478 Entries in this sequence describe source files that
1479 contribute to the line number information for this
1480 compilation or is used in other contexts, such as in
1481 a declaration coordinate or a macro file inclusion.
1482  
1483 The first entry in the sequence is the primary source file 
1484 whose file name exactly matches that given in the 
1485 \DWATname{} attribute in the compilation unit 
1486 debugging information entry.
1487    
1488 The line number program references file names in this 
1489 sequence beginning with 0, and uses those numbers instead 
1490 of file names in the line number program that follows.
1491
1492 \textit{Prior to \DWARFVersionV, the current compilation 
1493 file name was not represented in the \addttindex{file\_names}
1494 field. In \DWARFVersionV, the current compilation file name 
1495 is explicitly present and has index 0. This is needed to support 
1496 the common practice of stripping all but the line number sections
1497 (\dotdebugline{} and \dotdebuglinestr) from an executable.}
1498
1499 \textit{Note that if a \dotdebuglinestr{} section is present, 
1500 both the compilation unit debugging information entry 
1501 and the line number header can
1502 share a single copy of the current file name string.}
1503
1504 \end{enumerate}
1505
1506 \needlines{8}
1507 \subsubsection{Standard Content Descriptions}
1508 \label{chap:standardcontentdescriptions}
1509 DWARF-defined content type codes are used to indicate
1510 the type of information that is represented in one
1511 component of an include directory or file name description.
1512 The following type codes are defined.
1513 \begin{enumerate}[1. ]
1514
1515 \item  \DWLNCTpathTARG \\
1516 The component is a null-terminated path name string.
1517 If the associated form code is \DWFORMstring{}, then the
1518 string occurs immediately in the containing \texttt{directories}
1519 or \addttindex{file\_names} field. If the form code is \DWFORMlinestrp{},
1520 then the string is included in the \dotdebuglinestr{} section
1521 and its offset occurs immediately in the containing
1522 \addttindex{directories} or \addttindex{file\_names} field.
1523
1524 In the 32-bit DWARF format, the representation of a
1525 \DWFORMlinestrp{} value is a 4-byte unsigned offset; in the
1526 64-bit DWARF format, it is an 8-byte unsigned offset (see
1527 Section \refersec{datarep:32bitand64bitdwarfformats}).
1528
1529 \textit{Note that this use of \DWFORMlinestrp{} is similar to
1530 \DWFORMstrp{} but refers to the \dotdebuglinestr{} section,
1531 not \dotdebugstr.}
1532    
1533 In a \dotdebuglinedwo{} section, the form \DWFORMstrx{} may
1534 also be used. This refers into the \dotdebugstroffsetsdwo{}
1535 section (and indirectly also the \dotdebugstrdwo{} section)
1536 because no \texttt{.debug\_line\_str\_offsets.dwo} or 
1537 \texttt{.debug\_line\_str.dwo} sections exist or are defined for 
1538 use in split objects. (The form \DWFORMstring{} may also be used, 
1539 but this precludes the benefits of string sharing.)
1540    
1541 \item \DWLNCTdirectoryindexTARG \\
1542 The unsigned directory index represents an entry in the
1543 directories field of the header. The index is 0 if
1544 the file was found in the current directory of the compilation
1545 (hence, the first directory in the directories field),
1546 1 if it was found in the second directory in the directories
1547 field, and so on.
1548
1549 This content code is always paired with one of \DWFORMdataone, 
1550 \DWFORMdatatwo{} or \DWFORMudata.
1551
1552 \textit{The optimal form for a producer to use (which results in the
1553 minimum size for the set of \addttindex{include\_index} fields) depends not only
1554 on the number of directories in the directories
1555 field, but potentially on the order in which those directories are
1556 listed and the number of times each is used in the \addttindex{file\_names} field.}
1557
1558 \needlines{4}
1559 \item \DWLNCTtimestampTARG \\
1560 \DWLNCTtimestampNAME{} indicates that the value is the implementation-defined 
1561 time of last modification of the file, or 0 if not available. 
1562 It is always paired with one of the forms
1563 \DWFORMudata, \DWFORMdatafour, \DWFORMdataeight{} or \DWFORMblock.
1564    
1565 \item  \DWLNCTsizeTARG \\
1566 \DWLNCTsizeNAME{} indicates that the value is the unsigned size of the
1567 file in bytes, or 0 if not available. It is paired with one of the
1568 forms \DWFORMudata, \DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour{}
1569 or \DWFORMdataeight.
1570  
1571 \item \DWLNCTMDfiveTARG \\
1572 \DWLNCTMDfiveNAME{} indicates that the value is a 16-byte \MDfive{} digest
1573 of the file contents. It is paired with form \DWFORMdatasixteen.
1574 \end{enumerate}
1575
1576 \textit{An example that uses this line number header format
1577 is found in Appendix \refersec{app:linenumberheaderexample}.}
1578
1579 \subsubsection{Vendor-defined Content Descriptions}
1580 \label{chap:vendordefinedcontentdescriptions}
1581 Vendor-defined content descriptions may be defined using content
1582 type codes in the range \DWLNCTlouserNAME{} to \DWLNCThiuserNAME{}. Each
1583 such code may be combined with one or more forms from the set:
1584 \DWFORMblock, \DWFORMblockone, \DWFORMblocktwo, \DWFORMblockfour,
1585 \DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour, \DWFORMdataeight,
1586 \DWFORMdatasixteen,
1587 \DWFORMflag, \DWFORMlinestrp, \DWFORMsdata, \DWFORMsecoffset,
1588 \DWFORMstring, \DWFORMstrp, \DWFORMstrx{}  and \DWFORMudata.
1589
1590 If a consumer encounters a vendor-defined content type that
1591 it does not understand, it should skip the content data as though
1592 it were not present.
1593
1594 \needlines{6}
1595 \subsection{The Line Number Program}
1596 \label{chap:linenumberprogram}
1597 As stated before, the goal of a line number program is to build
1598 a matrix representing one compilation unit, which may have
1599 produced multiple sequences of target machine instructions.
1600 Within a sequence, addresses and 
1601 \addtoindex{operation pointer}s may only increase. 
1602 (Line numbers may decrease in cases of pipeline
1603 scheduling or other optimization.)
1604
1605 \needlines{4}
1606 \subsubsection{Special Opcodes} 
1607 \label{chap:specialopcodes}
1608 Each \HFTubyte{} special opcode has the following effect on the state machine:
1609
1610 \begin{enumerate}[1. ]
1611
1612 \item  Add a signed integer to the \texttt{line} register.
1613
1614 \item  Modify the \addtoindex{operation pointer} by incrementing the
1615 \texttt{address} and \addttindex{op\_index} registers as described below.
1616
1617 \item  Append a row to the matrix using the current values
1618 of the state machine registers.
1619
1620 \item  Set the \addttindex{basic\_block} register to \doublequote{false.} \addtoindexx{basic block}
1621 \item  Set the \addttindex{prologue\_end} register to \doublequote{false.}
1622 \item  Set the \addttindex{epilogue\_begin} register to \doublequote{false.}
1623 \item  Set the \addttindex{discriminator} register to 0.
1624
1625 \end{enumerate}
1626
1627 All of the special opcodes do those same seven things; they
1628 differ from one another only in what values they add to the
1629 \texttt{line}, \texttt{address} and \addttindex{op\_index} registers.
1630
1631
1632 \textit{Instead of assigning a fixed meaning to each special opcode,
1633 the line number program uses several parameters in the header
1634 to configure the instruction set. There are two reasons
1635 for this.  First, although the opcode space available for
1636 special opcodes ranges from 13 through 255, the lower
1637 bound may increase if one adds new standard opcodes. Thus, the
1638 \texttt{opcode\_base} field of the line number program header gives the
1639 value of the first special opcode. Second, the best choice of
1640 special\dash opcode meanings depends on the target architecture. For
1641 example, for a RISC machine where the compiler\dash generated code
1642 interleaves instructions from different lines to schedule
1643 the pipeline, it is important to be able to add a negative
1644 value to the \texttt{line} register to express the fact that a later
1645 instruction may have been emitted for an earlier source
1646 line. For a machine where pipeline scheduling never occurs,
1647 it is advantageous to trade away the ability to decrease
1648 the \texttt{line} register (a standard opcode provides an alternate
1649 way to decrease the line number) in return for the ability
1650 to add larger positive values to the \texttt{address} register. To
1651 permit this variety of strategies, the line number program
1652 header defines a 
1653 \addttindex{line\_base}
1654 field that specifies the minimum
1655 value which a special opcode can add to the line register
1656 and a 
1657 \addttindex{line\_range}
1658 field that defines the range of values it
1659 can add to the line register.}
1660
1661
1662 A special opcode value is chosen based on the amount that needs
1663 to be added to the \texttt{line}, \texttt{address} and \addttindex{op\_index} registers.
1664 The maximum line increment for a special opcode is the value
1665 of the 
1666 \addttindex{line\_base}
1667 field in the header, plus the value of the 
1668 \addttindex{line\_range} field, minus 1 (line base + 
1669 line range - 1). 
1670 If the desired line increment is greater than the maximum
1671 line increment, a standard opcode must be used instead of a
1672 special opcode. The \addtoindex{operation advance} represents the number
1673 of operations to skip when advancing the \addtoindex{operation pointer}.
1674
1675 \needlines{6}
1676 The special opcode is then calculated using the following formula:
1677 \begin{alltt}
1678   opcode = 
1679     (\textit{desired line increment} - \addttindex{line\_base}) +
1680       (\addttindex{line\_range} * \textit{operation advance}) + \addttindex{opcode\_base}
1681 \end{alltt}
1682 If the resulting opcode is greater than 255, a standard opcode
1683 must be used instead.
1684
1685 \textit{When \addttindex{maximum\_operations\_per\_instruction} is 1, 
1686 the operation advance is simply the address increment divided by the
1687 \addttindex{minimum\_instruction\_length}.}
1688
1689 \needlines{6}
1690 To decode a special opcode, subtract the \addttindex{opcode\_base} from
1691 the opcode itself to give the \textit{adjusted opcode}. 
1692 The \textit{operation advance} 
1693 is the result of the adjusted opcode divided by the
1694 \addttindex{line\_range}. The new \texttt{address} and 
1695 \addttindex{op\_index} values are given by
1696 \begin{alltt}
1697   \textit{adjusted opcode} = opcode \dash opcode\_base
1698   \textit{operation advance} = \textit{adjusted opcode} / line\_range
1699
1700   new address = address +
1701     \addttindex{minimum\_instruction\_length} *
1702       ((\addttindex{op\_index} + \addtoindex{operation advance}) / \addttindex{maximum\_operations\_per\_instruction})
1703
1704   new op\_index =
1705     (\addttindex{op\_index} + \addtoindex{operation advance}) \% \addttindex{maximum\_operations\_per\_instruction}
1706 \end{alltt}
1707
1708 \textit{When the \addttindex{maximum\_operations\_per\_instruction} 
1709 field is 1,
1710 \texttt{op\_index} is always 0 and these calculations simplify to 
1711 those given for addresses in \DWARFVersionIII{} and earlier.}
1712
1713 The amount to increment the line register is the 
1714 \addttindex{line\_base} plus
1715 the result of the 
1716 \textit{\addtoindex{adjusted opcode}} modulo the 
1717 \addttindex{line\_range}. That
1718 is,
1719
1720 \begin{alltt}
1721   line increment = \addttindex{line\_base} + (\textit{adjusted opcode} \% \addttindex{line\_range})
1722 \end{alltt}
1723
1724 \textit{See Appendix \refersec{app:linenumberspecialopcodeexample} for an example.}
1725
1726
1727 \needlines{6}
1728 \subsubsection{Standard Opcodes}
1729 \label{chap:standardopcodes}
1730
1731 The standard opcodes, their applicable operands and the
1732 actions performed by these opcodes are as follows:
1733
1734 \begin{enumerate}[1. ]
1735
1736 \item \textbf{\DWLNScopyTARG} \\
1737 The \DWLNScopyNAME{} 
1738 opcode takes no operands. It appends a row
1739 to the matrix using the current values of the state machine
1740 registers. Then it sets the \addttindex{discriminator} register to 0,
1741 and sets the \addttindex{basic\_block}, 
1742 \addttindex{prologue\_end} and 
1743 \addttindex{epilogue\_begin}
1744 registers to \doublequote{false.}
1745
1746 \needlines{5}
1747 \item \textbf{\DWLNSadvancepcTARG} \\
1748 The \DWLNSadvancepcNAME{} 
1749 opcode takes a single unsigned LEB128\addtoindexx{LEB128!unsigned}
1750 operand as the \addtoindex{operation advance} and modifies the \texttt{address}
1751 and \addttindex{op\_index} registers as specified in 
1752 Section \refersec{chap:specialopcodes}.
1753
1754 \item \textbf{\DWLNSadvancelineTARG} \\
1755 The \DWLNSadvancelineNAME{} 
1756 opcode takes a single signed LEB128\addtoindexx{LEB128!signed}
1757 operand and adds that value to the \texttt{line} register of the
1758 state machine.
1759
1760 \needlines{4}
1761 \item \textbf{\DWLNSsetfileTARG} \\ 
1762 The \DWLNSsetfileNAME{} opcode takes a single
1763 unsigned LEB128\addtoindexx{LEB128!unsigned} 
1764 operand and stores it in the \texttt{file} register
1765 of the state machine.
1766
1767 \needlines{4}
1768 \item \textbf{\DWLNSsetcolumnTARG} \\ 
1769 The \DWLNSsetcolumnNAME{} opcode takes a
1770 single unsigned LEB128\addtoindexx{LEB128!unsigned} operand 
1771 and stores it in the \texttt{column}
1772 register of the state machine.
1773
1774 \needlines{4}
1775 \item \textbf{\DWLNSnegatestmtTARG} \\
1776 The \DWLNSnegatestmtNAME{} opcode takes no
1777 operands. It sets the \addttindex{is\_stmt} register of the state machine
1778 to the logical negation of its current value.
1779
1780 \needlines{4}
1781 \item \textbf{\DWLNSsetbasicblockTARG} \\
1782 The \DWLNSsetbasicblockNAME{}
1783 opcode
1784 \addtoindexx{basic block}
1785 takes no operands. 
1786 It sets the \addttindex{basic\_block} register of the
1787 state machine to \doublequote{true.}
1788
1789 \item \textbf{\DWLNSconstaddpcTARG} \\
1790 The \DWLNSconstaddpcNAME{} opcode takes
1791 no operands. It advances the \texttt{address} and \addttindex{op\_index} registers
1792 by the increments corresponding to special opcode 255.
1793
1794 \textit{When the line number program needs to advance the \texttt{address}
1795 by a small amount, it can use a single special opcode,
1796 which occupies a single byte. When it needs to advance the
1797 \texttt{address} by up to twice the range of the last special opcode,
1798 it can use \DWLNSconstaddpc{} followed by a special opcode,
1799 for a total of two bytes. Only if it needs to advance the
1800 address by more than twice that range will it need to use
1801 both \DWLNSadvancepc{} and a special opcode, requiring three
1802 or more bytes.}
1803
1804 \item \textbf{\DWLNSfixedadvancepcTARG} \\ 
1805 The \DWLNSfixedadvancepcNAME{} opcode
1806 takes a single \HFTuhalf{} (unencoded) operand and adds it to the
1807 \texttt{address} register of the state machine and sets the \addttindex{op\_index}
1808 register to 0. This is the only standard opcode whose operand
1809 is \textbf{not} a variable length number. It also does 
1810 \textbf{not} multiply the
1811 operand by the \addttindex{minimum\_instruction\_length} 
1812 field of the header.
1813
1814 \textit{Some assemblers may not be able emit 
1815 \DWLNSadvancepc{} or special opcodes because they cannot encode 
1816 \addtoindex{LEB128} numbers or judge when
1817 the computation of a special opcode overflows and requires
1818 the use of \DWLNSadvancepc. Such assemblers, however, can
1819 use \DWLNSfixedadvancepc{} instead, sacrificing compression.}
1820
1821 \needlines{6}
1822 \item \textbf{\DWLNSsetprologueendTARG} \\
1823 The \DWLNSsetprologueendNAME{}
1824 opcode takes no operands. It sets the 
1825 \addttindex{prologue\_end} register
1826 to \doublequote{true.}
1827
1828 \textit{When a breakpoint is set on entry to a function, it is
1829 generally desirable for execution to be suspended, not on the
1830 very first instruction of the function, but rather at a point
1831 after the function's frame has been set up, after any language
1832 defined local declaration processing has been completed,
1833 and before execution of the first statement of the function
1834 begins. Debuggers generally cannot properly determine where
1835 this point is. This command allows a compiler to communicate
1836 the location(s) to use.}
1837
1838 \textit{In the case of optimized code, there may be more than one such
1839 location; for example, the code might test for a special case
1840 and make a fast exit prior to setting up the frame.}
1841
1842 \textit{Note that the function to which the 
1843 \addtoindex{prologue end} applies cannot
1844 be directly determined from the line number information alone;
1845 it must be determined in combination with the subroutine
1846 information entries of the compilation (including inlined
1847 subroutines).}
1848
1849
1850 \item \textbf{\DWLNSsetepiloguebeginTARG} \\
1851 The \DWLNSsetepiloguebeginNAME{} opcode takes no operands. It
1852 sets the \addttindex{epilogue\_begin} register to \doublequote{true.}
1853
1854 \textit{When a breakpoint is set on the exit of a function or execution
1855 steps over the last executable statement of a function, it is
1856 generally desirable to suspend execution after completion of
1857 the last statement but prior to tearing down the frame (so that
1858 local variables can still be examined). Debuggers generally
1859 cannot properly determine where this point is. This command
1860 allows a compiler to communicate the location(s) to use.}
1861
1862 \textit{Note that the function to which the 
1863 \addtoindex{epilogue end} applies cannot
1864 be directly determined from the line number information alone;
1865 it must be determined in combination with the subroutine
1866 information entries of the compilation (including inlined
1867 subroutines).}
1868
1869 \textit{In the case of a trivial function, both 
1870 \addtoindex{prologue end} and
1871 \addtoindex{epilogue begin} may occur at the same address.}
1872
1873 \item \textbf{\DWLNSsetisaTARG} \\
1874 The \DWLNSsetisaNAME{} opcode takes a single
1875 unsigned LEB128\addtoindexx{LEB128!unsigned} operand and stores that value in the 
1876 \addttindex{isa}
1877 register of the state machine.
1878 \end{enumerate}
1879
1880 \needlines{8}
1881 \subsubsection{Extended Opcodes}
1882 \label{chap:extendedopcodes}
1883
1884 The extended opcodes are as follows:
1885
1886 \begin{enumerate}[1. ]
1887
1888 \item \textbf{\DWLNEendsequenceTARG} \\
1889 The \DWLNEendsequenceNAME{} opcode takes no operands. It sets the
1890 \addttindex{end\_sequence}
1891 register of the state machine to \doublequote{true} and
1892 appends a row to the matrix using the current values of the
1893 state-machine registers. Then it resets the registers to the
1894 initial values specified above 
1895 (see Section \refersec{chap:statemachineregisters}). 
1896 Every line
1897 number program sequence must end with a \DWLNEendsequence{}
1898 instruction which creates a row whose address is that of the
1899 byte after the last target machine instruction of the sequence.
1900
1901 \needlines{5}
1902 \item \textbf{\DWLNEsetaddressTARG} \\
1903 The \DWLNEsetaddressNAME{} opcode takes a single relocatable
1904 address as an operand. The size of the operand is the size
1905 of an address on the target machine. It sets the \texttt{address}
1906 register to the value given by the relocatable address and
1907 sets the \addttindex{op\_index} register to 0.
1908
1909 \textit{All of the other line number program opcodes that
1910 affect the \texttt{address} register add a delta to it. This instruction
1911 stores a relocatable value into it instead.}
1912
1913 \item \textbf{\DWLNEsetdiscriminatorTARG} \\
1914 The \DWLNEsetdiscriminatorNAME{}
1915 opcode takes a single
1916 parameter, an unsigned LEB128\addtoindexx{LEB128!unsigned} 
1917 integer. It sets the
1918 \addttindex{discriminator} register to the new value.
1919
1920 \end{enumerate}
1921
1922 \textit{The DW\_LNE\_define\_file operation defined
1923 in earlier versions of DWARF is deprecated in \DWARFVersionV.}
1924 \addtoindexx{DW\_LNE\_define\_file  (deprecated)}
1925
1926 \textit{Appendix \refersec{app:linenumberprogramexample} 
1927 gives some sample line number programs.}
1928
1929 \section{Macro Information}
1930 \label{chap:macroinformation}
1931 \textit{Some languages, such as 
1932 \addtoindex{C} and 
1933 \addtoindex{C++}, provide a way to replace
1934 \addtoindexx{macro information}
1935 text in the source program with macros defined either in the
1936 source file itself, or in another file included by the source
1937 file.  Because these macros are not themselves defined in the
1938 target language, it is difficult to represent their definitions
1939 using the standard language constructs of DWARF. The debugging
1940 information therefore reflects the state of the source after
1941 the macro definition has been expanded, rather than as the
1942 programmer wrote it. The macro information table provides a way
1943 of preserving the original source in the debugging information.}
1944
1945 As described in 
1946 Section \refersec{chap:fullandpartialcompilationunitentries},
1947 the macro information for a
1948 given compilation unit is represented in the 
1949 \dotdebugmacro{}
1950 section of an object file. 
1951
1952 \needlines{4}
1953 \textit{The \dotdebugmacro{} section is new in 
1954 \DWARFVersionV, and supersedes the
1955 \dotdebugmacinfo{} section of earlier DWARF versions. 
1956 While \dotdebugmacro{} and \dotdebugmacinfo{}
1957 sections cannot both occur in the same compilation unit, both may be found in the 
1958 set of units that make up an executable or shared object file.}
1959
1960 \textit{The representation of debugging information in the \dotdebugmacinfo{} section is specified
1961 in earlier versions of the DWARF standard. Note that the \dotdebugmacinfo{} section does not contain 
1962 any headers and does not support sharing of strings or sharing of repeated macro sequences.}
1963
1964 The macro information for each compilation unit consists of one or
1965 more macro units.  Each macro unit starts with a header
1966 and is followed by a series of macro information entries or file
1967 inclusion entries.  Each entry consists of an opcode followed by
1968 zero or more operands. Each macro unit ends with an entry
1969 containing an opcode of 0.
1970
1971 In all macro information entries,
1972 the line number of the entry is encoded as an
1973 unsigned LEB128 integer.
1974
1975 \needlines{6}
1976 \subsection{Macro Information Header}
1977 The macro information header contains the following fields:
1978
1979 \begin{enumerate}[1. ]
1980 \item \texttt{version} (\HFTuhalf) \\
1981 A version number (see Section \refersec{datarep:macroinformation}).
1982 This number is specific to the macro information and is independent
1983 of the DWARF version number.
1984
1985 \item \texttt{flags} (\HFTubyte) \\
1986 The bits of the \texttt{flags} field are interpreted as a set
1987 of flags, some of which may indicate that additional fields follow.
1988
1989 \needlines{4}
1990 The following flags, beginning with the least significant bit, are defined:
1991 \begin{itemize}
1992 \item \HFNoffsetsizeflag \\
1993 If the \HFNoffsetsizeflag{} is zero, the header is for a 32-bit 
1994 DWARF format macro section and all offsets are 4 bytes long;
1995 if it is one, the header is for a 64-bit DWARF format macro section 
1996 and all offsets are 8 bytes long.
1997
1998 \item \addttindex{debug\_line\_offset\_flag} \\
1999 If the \addttindex{debug\_line\_offset\_flag} is one, 
2000 the \addttindex{debug\_line\_offset} field (see below) is present. 
2001 If zero, that field is omitted.
2002
2003 \item \addttindex{opcode\_operands\_table\_flag} \\
2004 If the \addttindex{opcode\_operands\_table\_flag} is one,
2005 the \addttindex{opcode\_operands\_table} field (see below) is present.
2006 If zero, that field is omitted.
2007
2008 \end{itemize}
2009 All other flags are reserved by DWARF.
2010
2011 \item \addttindex{debug\_line\_offset} \\
2012 An offset in the \dotdebugline{} section of the
2013 beginning of the line number information in the containing
2014 compilation, encoded as a 4-byte offset for a 32-bit DWARF 
2015 format macro section and an 8-byte offset for a 64-bit DWARF format
2016 macro section.  
2017
2018 \item \addttindex{opcode\_operands\_table} \\
2019 An \texttt{opcode\_operands\_table} describing the operands 
2020 of the macro information entry opcodes.
2021
2022 The macro information entries defined in this standard may, but need not, be
2023 described in the table, while other user-defined entry opcodes used in the section
2024 are described there.  Vendor extension entry opcodes are
2025 allocated in the range from \DWMACROlouser{} to \DWMACROhiuser. Other
2026 unassigned codes are reserved for future DWARF standards.
2027
2028 \needlines{4}
2029 The table starts with a 1-byte \texttt{count} of the defined opcodes, followed by
2030 an entry for each of those opcodes.  Each entry starts with a 1-byte unsigned
2031 opcode number, followed by unsigned LEB128\addtoindexx{ULEB128} encoded number of operands
2032 and for each operand there is a single unsigned byte describing the form in which
2033 the operand is encoded.  The allowed forms are: 
2034 \DWFORMblock, \DWFORMblockone, \DWFORMblocktwo, \DWFORMblockfour,
2035 \DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour, \DWFORMdataeight, 
2036 \DWFORMdatasixteen, \DWFORMsdata, \DWFORMudata, \DWFORMflag, \DWFORMsecoffset,
2037 \DWFORMstring, \DWFORMstrp{} and \DWFORMstrx.
2038 \end{enumerate}
2039
2040 \subsection{Macro Information Entries}
2041 \label{chap:macroinformationentries}
2042 All macro information entries within a \dotdebugmacro{}
2043 section for a given compilation unit appear in the same 
2044 order in which the directives were processed by the 
2045 compiler (after taking into account the effect of the
2046 macro import directives).
2047
2048 \textit{The source file in which a macro information entry occurs
2049 can be derived by interpreting the sequence of entries from the
2050 beginning of the \dotdebugmacro{} section. \DWMACROstartfile{} and 
2051 \DWMACROendfile{} indicate changes in the containing file.} 
2052
2053 \subsubsection{Define and Undefine Entries}
2054 \label{chap:defineandundefineentries}
2055 The define and undefine macro entries have multiple forms that
2056 use different representations of their two operands.
2057
2058 While described in pairs below, the forms of define 
2059 and undefine entries may be freely intermixed.
2060
2061 \begin{enumerate}[1. ]
2062
2063 \itembfnl{\DWMACROdefineTARG{}, \DWMACROundefTARG{}}
2064 A \DWMACROdefineNAME{} or \DWMACROundefNAME{} entry has two
2065 operands. The first operand encodes the source line number 
2066 of the \texttt{\#define} or \texttt{\#undef} macro directive.
2067 The second operand is a null-terminated character
2068 string for the macro being defined or undefined. 
2069
2070 The contents of the operands are described below (see Sections 
2071 \ref{chap:macrodefinestring} and \referfol{chap:macroundefinestring}).
2072
2073 \itembfnl{\DWMACROdefinestrpTARG{}, \DWMACROundefstrpTARG{}}
2074 A \DWMACROdefinestrpNAME{} or \DWMACROundefstrpNAME{} 
2075 entry has two operands.  The first operand encodes the source line number
2076 of the \texttt{\#define} or \texttt{\#undef} macro directive. 
2077 The second operand consists of an offset into a string table contained in
2078 the \dotdebugstr{} section of the object file.  The size of the operand is
2079 given in the header \HFNoffsetsizeflag{} field. 
2080
2081 The contents of the operands are described below (see Sections 
2082 \ref{chap:macrodefinestring} and \referfol{chap:macroundefinestring}).
2083
2084 \itembfnl{\DWMACROdefinestrxTARG{}, \DWMACROundefstrxTARG{}}
2085 A \DWMACROdefinestrxNAME{} or \DWMACROundefstrxNAME{} entry 
2086 has two operands.  The first operand encodes the line number 
2087 of the \texttt{\#define} or \texttt{\#undef} macro directive.
2088 The second operand identifies a string; it is represented using an 
2089 unsigned LEB128\addtoindexx{ULEB128} encoded value,
2090 which is interpreted as a zero-based index into an array of offsets in the
2091 \dotdebugstroffsets{} section. 
2092
2093 The contents of the operands are described below (see Sections 
2094 \ref{chap:macrodefinestring} and \referfol{chap:macroundefinestring}).
2095
2096 \needlines{6}
2097 \itembfnl{\DWMACROdefinesupTARG{}, \DWMACROundefsupTARG{}}
2098 A \DWMACROdefinesupNAME{} or \DWMACROundefsupNAME{} entry 
2099 has two operands.  The first operand encodes the line number 
2100 of the \texttt{\#define} or \texttt{\#undef} macro directive.
2101 The second operand identifies a string; it is represented as
2102 an offset into a string table contained in the \dotdebugstr{} 
2103 section of the \addtoindex{supplementary object file}.  
2104 The size of the operand depends on the macro section header 
2105 \HFNoffsetsizeflag{} field.  
2106
2107 The contents of the operands are described below (see Sections 
2108 \ref{chap:macrodefinestring} and \referfol{chap:macroundefinestring}).
2109
2110 \end{enumerate}
2111
2112
2113 \subsubsection{Macro Define String}
2114 \label{chap:macrodefinestring}
2115 In the case of a 
2116 \DWMACROdefine{},
2117 \DWMACROdefinestrp{},
2118 \DWMACROdefinestrx{} or
2119 \DWMACROdefinesup{}
2120 entry, the value of the
2121 second operand is the name of the macro symbol that is defined
2122 at the indicated source line, followed immediately by the 
2123 \addtoindex{macro formal parameter list}
2124 including the surrounding parentheses (in
2125 the case of a function-like macro) followed by the definition
2126 string for the macro. If there is no formal parameter list,
2127 then the name of the defined macro is followed immediately by
2128 its definition string.
2129
2130 In the case of a function-like macro definition, no whitespace
2131 characters appear between the name of the defined
2132 macro and the following left parenthesis. Formal parameters
2133 are separated by a comma without any whitespace.
2134 Exactly one space
2135 character separates the right parenthesis that terminates
2136 the formal parameter list and the following definition string.
2137
2138 In the case of a \doublequote{normal} (that is, non-function-like) macro
2139 definition, exactly one space character separates the
2140 name of the defined macro from the following definition text.
2141
2142 \subsubsection{Macro Undefine String}
2143 \label{chap:macroundefinestring}
2144 In the case of a 
2145 \DWMACROundef{},
2146 \DWMACROundefstrp{},
2147 \DWMACROundefstrx{} or
2148 \DWMACROundefsup{}
2149 entry, the value of the second string is the name of the pre-processor
2150 symbol that is undefined at the indicated source line.
2151
2152 \subsubsection{Entries for Command Line Options}
2153 \label{chap:entriesforcommandlineoptions}
2154 \DWMACROdefineINDX{}\DWMACROdefinestrpINDX{}\DWMACROdefinestrxINDX
2155 \DWMACROundefINDX{}\DWMACROundefstrpINDX{}\DWMACROundefstrxINDX
2156 A DWARF producer
2157 generates a define or undefine entry for
2158 each pre-processor symbol which is defined or undefined by
2159 some means other than such a directive
2160 within the compiled source text. In particular, pre-processor
2161 symbol definitions and undefinitions which occur as a
2162 result of command line options (when invoking the compiler)
2163 are represented by their own define and
2164 undefine entries.
2165
2166 All such define and undefine entries representing compilation 
2167 options appear before the first \DWMACROstartfile{} 
2168 entry for that compilation unit
2169 (see Section \referfol{chap:fileinclusionentries})
2170 and encode the value 0 in their line number operands.
2171
2172 \subsection{File Inclusion Entries}
2173 \label{chap:fileinclusionentries}
2174
2175 \subsubsection{Source Include Directives}
2176 \label{chap:sourceincludedirectives}
2177
2178 The following directives describe a source
2179 file inclusion directive (\texttt{\#include} in
2180 \addtoindex{C}/\addtoindex{C++}) and the
2181 ending of an included file.
2182
2183 \begin{enumerate}[1. ]
2184
2185 \itembfnl{\DWMACROstartfileTARG{}}
2186 A \DWMACROstartfileNAME{} entry has two operands. The
2187 first operand encodes the line number of the source line on
2188 which the \texttt{\#include} macro directive occurs. 
2189 The second operand encodes a source file name index. 
2190
2191 The source file name index is the file number in the 
2192 line number information table for the compilation unit.
2193
2194 If a \DWMACROstartfileNAME{} entry is present, the header
2195 contains a reference to the \dotdebugline{} section of 
2196 the compilation.
2197
2198 \itembfnl{\DWMACROendfileTARG{}}
2199 A \DWMACROendfileNAME{} entry has no operands. The presence of
2200 the entry marks the end of the current source file inclusion.
2201
2202 \end{enumerate}
2203
2204 \needlines{4}
2205 When providing macro information in an object file,
2206 a producer generates \DWMACROstartfile{} and
2207 \DWMACROendfile{} entries for the source file submitted to
2208 the compiler for compilation. This \DWMACROstartfile{} entry
2209 has the value 0 in its line number operand and references
2210 the file entry in the line number information table for the
2211 primary source file.
2212
2213 \subsubsection{Importation of Macro Units}
2214 \label{chap:importationofmacrounits}
2215 The import entries make it possible to replicate macro units.
2216 The first form supports replication within the current compilation
2217 and the second form supports replication across separate 
2218 executable or shared object files.
2219
2220 \textit{Import entries do not reflect the source program
2221 and, in fact, are not necessary at all. However, they do
2222 provide a mechanism that can be used to reduce redundancy
2223 in the macro information and thereby to save space.}
2224
2225 \begin{enumerate}[1. ]
2226
2227 \itembfnl{\DWMACROimportTARG{}}
2228 A \DWMACROimportNAME{} entry has one operand, an offset into
2229 another part of the \dotdebugmacro{} section that is
2230 the beginning of a target macro unit. The size of the operand
2231 depends on the header \HFNoffsetsizeflag{} field.  The
2232 \DWMACROimportNAME{} entry instructs the consumer to
2233 replicate the sequence of entries following the target macro 
2234 header which begins at the given 
2235 \dotdebugmacro{} offset, up to, but excluding,
2236 the terminating entry with opcode \texttt{0},
2237 as though it occurs in place of the import operation.
2238
2239 \itembfnl{\DWMACROimportsupTARG}
2240 A \DWMACROimportsupNAME{} entry has one operand, an 
2241 offset from the start of the \dotdebugmacro{} section in the 
2242 \addtoindex{supplementary object file}.  
2243 The size of the operand depends on the section header 
2244 \HFNoffsetsizeflag{} field. 
2245 Apart from the different location in which to find the macro unit,
2246 this entry type is equivalent to \DWMACROimport. 
2247
2248 \textit{This entry type is aimed at sharing duplicate 
2249 macro units between \dotdebugmacro{}
2250 sections from different executable or shared object files.}  
2251
2252 \needlines{4}
2253 From within the \dotdebugmacro{} section of the 
2254 \addtoindex{supplementary object file}, \DWMACROdefinestrp{} 
2255 and \DWMACROundefstrp{} entries refer to the
2256 \dotdebugstr{} section of that same supplementary file;
2257 similarly, \DWMACROimport{} entries refer to the 
2258 \dotdebugmacro{} section of that same supplementary file.
2259
2260 \end{enumerate}
2261
2262
2263 \needlines{6}
2264 \section{Call Frame Information}
2265 \label{chap:callframeinformation}
2266 \addtoindexx{unwind|see{virtual unwind}}\addtoindexx{virtual unwind}
2267
2268 \textit{Debuggers often need to be able to view and modify the 
2269 state of any subroutine activation that is
2270 \addtoindexx{activation of call frame}
2271 on the call stack. An activation consists of:}
2272
2273 \begin{itemize}
2274 \item \textit{A code location that is within the
2275 subroutine. This location is either the place where the program
2276 stopped when the debugger got control (for example, a breakpoint), or
2277 is a place where a subroutine made a call or was interrupted
2278 by an asynchronous event (for example, a signal).}
2279
2280 \item \textit{An area of memory that is allocated on a stack called a
2281 \doublequote{call frame.} The call frame is identified by an address
2282 on the stack. We refer to this address as the Canonical
2283 Frame Address or CFA. Typically, the CFA is defined to be the
2284 value of the stack pointer at the call site in the previous
2285 frame (which may be different from its value on entry to the
2286 current frame).}
2287
2288 \item \textit{A set of registers that are in use by the subroutine
2289 at the code location.}
2290
2291 \end{itemize}
2292
2293 \textit{Typically, a set of registers are designated to be preserved
2294 across a call. If a callee wishes to use such a register, it
2295 saves the value that the register had at entry time in its call
2296 frame and restores it on exit. The code that allocates space
2297 on the call frame stack and performs the save operation is
2298 called the subroutine\textquoteright{s} \addtoindex{prologue}, and the code that performs
2299 the restore operation and deallocates the frame is called its
2300 \addtoindex{epilogue}. Typically, the 
2301 \addtoindex{prologue} code is physically at the
2302 beginning of a subroutine and the 
2303 \addtoindex{epilogue} code is at the end.}
2304
2305 \textit{To be able to view or modify an activation that is not
2306 on the top of the call frame stack, the debugger must
2307 virtually unwind the stack of activations until
2308 it finds the activation of interest.  A debugger virtually unwinds
2309 a stack in steps. Starting with the current activation it
2310 virtually restores any registers that were preserved by the
2311 current activation and computes the predecessor\textquoteright{s} CFA and
2312 code location. This has the logical effect of returning from
2313 the current subroutine to its predecessor. We say that the
2314 debugger virtually unwinds the stack because the actual state
2315 of the target process is unchanged.}
2316
2317 \needlines{4}
2318 \textit{The virtual unwind 
2319 operation needs to know where registers are
2320 saved and how to compute the predecessor\textquoteright{s} CFA and code
2321 location. When considering an architecture-independent way
2322 of encoding this information one has to consider a number of
2323 special things:}
2324
2325 \begin{itemize} % bullet list
2326
2327 \item \textit{Prologue 
2328 \addtoindexx{prologue}
2329 and 
2330 \addtoindex{epilogue} code is not always in 
2331 distinct \nolink{blocks}
2332 at the beginning and end of a subroutine. It is common
2333 to duplicate the \addtoindex{epilogue} code 
2334 at the site of each return
2335 from the code. Sometimes a compiler breaks up the register
2336 save/unsave operations and moves them into the body of the
2337 subroutine to just where they are needed.}
2338
2339
2340 \item \textit{Compilers use different ways to manage the call
2341 frame. Sometimes they use a frame pointer register, sometimes
2342 not.}
2343
2344 \item \textit{The algorithm to compute CFA changes as you progress through
2345 the \addtoindex{prologue} 
2346 and \addtoindex{epilogue code}. 
2347 (By definition, the CFA value
2348 does not change.)}
2349
2350 \item \textit{Some subroutines have no call frame.}
2351
2352 \item \textit{Sometimes a register is saved in another register that by
2353 convention does not need to be saved.}
2354
2355 \item \textit{Some architectures have special instructions that perform
2356 some or all of the register management in one instruction,
2357 leaving special information on the stack that indicates how
2358 registers are saved.}
2359
2360 \item \textit{Some architectures treat return address values specially. For
2361 example, in one architecture, the call instruction guarantees
2362 that the low order two bits will be zero and the return
2363 instruction ignores those bits. This leaves two bits of
2364 storage that are available to other uses that must be treated
2365 specially.}
2366
2367 \end{itemize}
2368
2369
2370 \needlines{6}
2371 \subsection{Structure of Call Frame Information}
2372 \label{chap:structureofcallframeinformation}
2373
2374 DWARF supports virtual unwinding by defining an architecture
2375 independent basis for recording how subprograms save and restore
2376 registers during their lifetimes. This basis must be augmented
2377 on some machines with specific information that is defined by
2378 an architecture specific ABI authoring committee, a hardware
2379 vendor, or a compiler producer. The body defining a specific
2380 augmentation is referred to below as the \doublequote{augmenter.}
2381
2382 \needlines{8}
2383 Abstractly, this mechanism describes a very large table that
2384 has the following structure:
2385
2386 \begin{verbatim}
2387         LOC CFA R0 R1 ... RN
2388         L0
2389         L1
2390         ...
2391         LN
2392 \end{verbatim}
2393
2394
2395 The first column indicates an address for every location
2396 that contains code in a program. (In shared object files, this
2397 is an object-relative offset.) The remaining columns contain
2398 virtual unwinding rules that are associated with the indicated
2399 location.
2400
2401 The CFA column defines the rule which computes the Canonical
2402 Frame Address value; it may be either a register and a signed
2403 offset that are added together, or a DWARF expression that
2404 is evaluated.
2405
2406 \needlines{4}
2407 The remaining columns are labelled by register number. This
2408 includes some registers that have special designation on
2409 some architectures such as the PC and the stack pointer
2410 register. (The actual mapping of registers for a particular
2411 architecture is defined by the augmenter.) The register columns
2412 contain rules that describe whether a given register has been
2413 saved and the rule to find the value for the register in the
2414 previous frame.
2415
2416 \needlines{6}
2417 The register rules are:
2418
2419 \begin{longtable}{lP{9cm}}
2420 undefined 
2421 &A register that has this rule has no recoverable value in the previous frame.
2422 (By convention, it is not preserved by a callee.) \\
2423
2424 same value
2425 &This register has not been modified from the previous frame. (By convention,
2426 it is preserved by the callee, but the callee has not modified it.) \\
2427
2428 offset(N)
2429 &The previous value of this register is saved at the address CFA+N where CFA
2430 is the current CFA value and N is a signed offset.\\
2431
2432 val\_offset(N)
2433 &The previous value of this register is the value CFA+N where CFA is the
2434 current CFA value and N is a signed offset.\\
2435
2436 register(R)
2437 &The previous value of this register is stored 
2438 in another register numbered R.\\
2439
2440 expression(E)
2441 &The previous value of this register is located at the address produced by
2442 executing the DWARF expression E (see Section \refersec{chap:dwarfexpressions}).\\
2443
2444 val\_expression(E) 
2445 &The previous value of this register is the value produced by executing the
2446 DWARF expression E (see Section \refersec{chap:dwarfexpressions}).\\
2447
2448 architectural
2449 &The rule is defined externally to this specification by the augmenter.\\
2450
2451 \end{longtable}
2452
2453 \textit{This table would be extremely large if actually constructed
2454 as described. Most of the entries at any point in the table
2455 are identical to the ones above them. The whole table can be
2456 represented quite compactly by recording just the differences
2457 starting at the beginning address of each subroutine in
2458 the program.}
2459
2460 \needlines{4}
2461 The virtual unwind information is encoded in a self-contained
2462 section called 
2463 \dotdebugframe{}.  Entries in a 
2464 \dotdebugframe{} section
2465 are aligned on a multiple of the address size relative to
2466 the start of the section and come in two forms: a Common
2467 \addtoindexx{common information entry}
2468 Information Entry (CIE) and a 
2469 \addtoindexx{frame description entry}
2470 Frame Description Entry (FDE).
2471
2472 \textit{If the range of code addresses for a function is not
2473 contiguous, there may be multiple CIEs and FDEs corresponding
2474 to the parts of that function.}
2475
2476 \needlines{6}
2477 A Common Information Entry holds information that is shared
2478 among many Frame Description Entries. There is at least one
2479 CIE in every non-empty \dotdebugframe{} section. A CIE contains
2480 the following fields, in order:
2481 \begin{enumerate}[1. ]
2482 \item \HFNlength{} (\livelink{datarep:initiallengthvalues}{initial length})  \\
2483 A constant that gives the number of bytes of the CIE structure,
2484 not including the length field itself 
2485 (see Section \refersec{datarep:initiallengthvalues}). 
2486 The
2487 size of the \texttt{length} field plus the value of \texttt{length} must be an
2488 integral multiple of the address size.
2489
2490 \item  \HFNCIEid{} (4 or 8 bytes, see Section \refersec{datarep:32bitand64bitdwarfformats}) \\
2491 A constant that is used to distinguish CIEs from FDEs.
2492
2493 \item  \HFNversion{} (\HFTubyte) \\
2494 A version number\addtoindexx{version number!call frame information} 
2495 (see Section \refersec{datarep:callframeinformation}). 
2496 This number is specific to the call frame information
2497 and is independent of the DWARF version number.
2498
2499 \needlines{8}
2500 \item  \HFNaugmentation{} (\HFTaugstring) \\
2501 A null-terminated UTF\dash 8 string that identifies the augmentation
2502 to this CIE or to the FDEs that use it. If a reader encounters
2503 an augmentation string that is unexpected, then only the
2504 following fields can be read:
2505
2506
2507 \begin{itemize}
2508
2509 \item CIE: \HFNlength, \HFNCIEid, \HFNversion, \HFNaugmentation
2510
2511 \item FDE: \HFNlength, \HFNCIEpointer, \HFNinitiallocation, \HFNaddressrange
2512
2513 \end{itemize}
2514 If there is no augmentation, this value is a zero byte.
2515
2516 \needlines{5}
2517 \textit{The augmentation string allows users to indicate that there
2518 is additional target\dash specific information in the CIE or FDE
2519 which is needed to virtually 
2520 unwind a stack frame. For example, this
2521 might be information about dynamically allocated data which
2522 needs to be freed on exit from the routine.}
2523
2524 \textit{Because the \dotdebugframe{} section is useful independently of
2525 any \dotdebuginfo{} section, the augmentation string always uses
2526 UTF\dash 8 encoding.}
2527
2528 \needlines{4}
2529 \item \HFNaddresssize{} (\HFTubyte) \\
2530 The size of a target address in this CIE and any FDEs that
2531 use it, in bytes. If a compilation unit exists for this frame,
2532 its address size must match the address size here.
2533
2534 \item \HFNsegmentselectorsize{} (\HFTubyte) \\
2535 The size of a segment selector in this CIE and any FDEs that
2536 use it, in bytes.
2537
2538 \item \HFNcodealignmentfactor{} (unsigned LEB128) 
2539 \addtoindexx{LEB128!unsigned}\addtoindexx{unsigned LEB128|see{LEB128, unsigned}}
2540 \addtoindexx{code alignment factor} \\
2541
2542 \addtoindexx{\textless caf\textgreater|see{code alignment factor}}
2543 constant that is factored out of all advance location
2544 instructions (see 
2545 Section \refersec{chap:rowcreationinstructions}).
2546 The resulting value is  
2547 \mbox{\textit{(operand} * \HFNcodealignmentfactor)}.
2548
2549 \item  \HFNdataalignmentfactor{} (signed LEB128)
2550 \addtoindexx{LEB128!signed}\addtoindexx{signed LEB128|see{LEB128, signed}} \\
2551 \addtoindexx{data alignment factor}
2552
2553 \addtoindexx{\textless daf\textgreater|see{data alignment factor}}
2554 constant that is factored out of certain offset instructions
2555 (see Sections \refersec{chap:cfadefinitioninstructions} and 
2556 \refersec{chap:registerruleinstructions}).
2557 The resulting value is  \textit{(operand} *
2558 \HFNdataalignmentfactor).
2559
2560 \item  \HFNreturnaddressregister{} (unsigned LEB128)\addtoindexx{LEB128!unsigned} \\
2561 An unsigned LEB128 constant that indicates which column in the
2562 rule table represents the return address of the function. Note
2563 that this column might not correspond to an actual machine
2564 register.
2565
2566 \needlines{8}
2567 \item \HFNinitialinstructions{} (array of \HFTubyte) \\
2568 A sequence of rules that are interpreted to create the initial
2569 setting of each column in the table.  
2570
2571 The default rule for
2572 all columns before interpretation of the initial instructions
2573 is the undefined rule. However, an ABI authoring body or a
2574 compilation system authoring body may specify an alternate
2575 default value for any or all columns.
2576
2577 \item \HFNpadding{} (array of \HFTubyte) \\
2578 Enough \DWCFAnop{} instructions to make the size of this entry
2579 match the length value above.
2580 \end{enumerate}
2581
2582 \needlines{5}
2583 An FDE contains the following fields, in order:
2584 \begin{enumerate}[1. ]
2585 \item \HFNlength{} (\livelink{datarep:initiallengthvalues}{initial length})  \\
2586 A constant that gives the number of bytes of the header and
2587 instruction stream for this function, not including the length
2588 field itself 
2589 (see Section \refersec{datarep:initiallengthvalues}). 
2590 The size of the \texttt{length} field
2591 plus the value of length must be an integral multiple of the
2592 address size.
2593
2594 \item \HFNCIEpointer{} (4 or 8 bytes, see Section \refersec{datarep:32bitand64bitdwarfformats}) \\
2595 A constant 
2596 \addtoindexx{section offset!in FDE header}
2597 offset into the \dotdebugframe{}
2598 section that denotes
2599 the CIE that is associated with this FDE.
2600
2601 \needlines{4}
2602 \item  \HFNinitiallocation{} (segment selector and target address) \\
2603 The address of the first location associated with this table
2604 entry. 
2605 If the \HFNsegmentselectorsize{} field of this FDE's CIE is non-zero,
2606 the initial location is preceded by a segment selector of
2607 the given length.
2608
2609 \needlines{4}
2610 \item  \HFNaddressrange{} (target address) \\
2611 The number 
2612 \addtoindexx{target address}
2613 of bytes of program instructions described by this entry.
2614
2615 \item \HFNinstructions{} (array of \HFTubyte) \\
2616 A sequence of table defining instructions that are described 
2617 in Section \refersec{chap:callframeinstructions}.
2618
2619 \needlines{4}
2620 \item \HFNpadding{} (array of \HFTubyte) \\
2621 Enough \DWCFAnop{} instructions 
2622 to make the size of this entry match the \HFNlength{} value above.
2623 \end{enumerate}
2624
2625 \needlines{8}
2626 \subsection{Call Frame Instructions}
2627 \label{chap:callframeinstructions}
2628
2629 Each call frame instruction is defined to take 0 or more
2630 operands. Some of the operands may be encoded as part of the
2631 opcode 
2632 (see Section \refersec{datarep:callframeinformation}). 
2633 The instructions are defined in
2634 the following sections.
2635
2636 \needlines{8}
2637 Some call frame instructions have operands that are encoded
2638 as DWARF expressions 
2639 (see Section \refersec{chap:generaloperations}). 
2640 The following DWARF
2641 operators cannot be used in such operands:
2642
2643
2644 \begin{itemize}
2645 \item
2646 \DWOPaddrx, \DWOPcalltwo, \DWOPcallfour{}, \DWOPcallref, 
2647 \DWOPconsttype, \DWOPconstx, \DWOPconvert, \DWOPdereftype, 
2648 \DWOPregvaltype{} and \DWOPreinterpret{}
2649 operators are 
2650 not allowed in an operand of these instructions because
2651 the call frame information must not depend on other
2652 debug sections.
2653
2654 \needlines{5}
2655 \item \DWOPpushobjectaddress{} is not meaningful in an operand
2656 of these instructions because there is no object context to
2657 provide a value to push.
2658
2659 \item \DWOPcallframecfa{} is not meaningful in an operand of
2660 these instructions because its use would be circular.
2661 \end{itemize}
2662
2663 \textit{Call frame instructions to which these restrictions apply
2664 include \DWCFAdefcfaexpression, \DWCFAexpression{}
2665 and \DWCFAvalexpression.}
2666
2667 \needlines{8}
2668 \subsubsection{Row Creation Instructions}
2669 \label{chap:rowcreationinstructions}
2670 \begin{enumerate}[1. ]
2671
2672 \item \textbf{\DWCFAsetlocTARG} \\
2673 The \DWCFAsetlocNAME{} instruction 
2674 takes a single operand that
2675 represents a target address. The required action is to create a
2676 new table row using the specified address as the location. All
2677 other values in the new row are initially identical to the
2678 current row. The new location value is always greater than
2679 the current one. 
2680 If the \HFNsegmentselectorsize{} field of this FDE's 
2681 \addtoindex{CIE}
2682 is non-zero, the initial location is preceded by a segment
2683 selector of the given length.
2684
2685 \needlines{4}
2686 \item \textbf{\DWCFAadvancelocTARG} \\
2687 The \DWCFAadvancelocNAME{} instruction takes a single operand (encoded
2688 with the opcode) that represents a constant delta. The required
2689 action is to create a new table row with a location value that
2690 is computed by taking the current entry\textquoteright s location value
2691 and adding the value of 
2692 \textit{delta} * \addttindex{code\_alignment\_factor}. 
2693 All other values in the new row are initially identical to the
2694 current row
2695
2696 \needlines{6}
2697 \item \textbf{\DWCFAadvanceloconeTARG{}} \\
2698 The \DWCFAadvanceloconeNAME{} instruction takes a single \HFTubyte{}
2699 operand that represents a constant delta. This instruction
2700 is identical to \DWCFAadvanceloc{} except for the encoding
2701 and size of the delta operand.
2702
2703 \item \textbf{\DWCFAadvanceloctwoTARG} \\
2704 The \DWCFAadvanceloctwoNAME{} instruction takes a single \HFTuhalf{}
2705 operand that represents a constant delta. This instruction
2706 is identical to \DWCFAadvanceloc{} except for the encoding
2707 and size of the delta operand.
2708
2709 \item \textbf{\DWCFAadvancelocfourTARG} \\
2710 The \DWCFAadvancelocfourNAME{} instruction takes a single \HFTuword{}
2711 operand that represents a constant delta. This instruction
2712 is identical to \DWCFAadvanceloc{} except for the encoding
2713 and size of the delta operand.
2714
2715 \end{enumerate}
2716
2717 \subsubsection{CFA Definition Instructions}
2718 \label{chap:cfadefinitioninstructions}
2719 \begin{enumerate}[1. ]
2720
2721 \item \textbf{\DWCFAdefcfaTARG} \\
2722 The \DWCFAdefcfaNAME{}
2723 instruction takes two unsigned LEB128\addtoindexx{LEB128!unsigned}
2724 operands representing a register number and a (non-factored)
2725 offset. The required action is to define the current CFA rule
2726 to use the provided register and offset.
2727
2728 \needlines{6}
2729 \item \textbf{\DWCFAdefcfasfTARG} \\
2730 The \DWCFAdefcfasfNAME{} instruction takes two operands:
2731 an unsigned LEB128 value\addtoindexx{LEB128!unsigned}
2732 representing a register number and a
2733 signed LEB128\addtoindexx{LEB128!signed} factored offset. This instruction is identical
2734 to \DWCFAdefcfa{} except that the second operand is signed
2735 and factored. The resulting offset is \textit{factored\_offset} *
2736 \addttindex{data\_alignment\_factor}.
2737
2738
2739 \item \textbf{\DWCFAdefcfaregisterTARG} \\
2740 The \DWCFAdefcfaregisterNAME{} 
2741 instruction takes a single
2742 unsigned LEB128\addtoindexx{LEB128!unsigned} operand representing a register number. The
2743 required action is to define the current CFA rule to use
2744 the provided register (but to keep the old offset). This
2745 operation is valid only if the current CFA rule is defined
2746 to use a register and offset.
2747
2748
2749 \needlines{5}
2750 \item \textbf{\DWCFAdefcfaoffsetTARG} \\
2751 The \DWCFAdefcfaoffsetNAME{} instruction takes a single
2752 unsigned LEB128\addtoindexx{LEB128!unsigned} operand representing a (non-factored)
2753 offset. The required action is to define the current CFA rule
2754 to use the provided offset (but to keep the old register). This
2755 operation is valid only if the current CFA rule is defined
2756 to use a register and offset.
2757
2758 \needlines{6}
2759 \item \textbf{\DWCFAdefcfaoffsetsfTARG} \\
2760 The \DWCFAdefcfaoffsetsfNAME{} instruction takes a signed
2761 LEB128\addtoindexx{LEB128!signed} operand representing a factored offset. This instruction
2762 is identical to \DWCFAdefcfaoffset{} except that the
2763 operand is signed and factored. The resulting offset is
2764 \textit{factored\_offset} * \addttindex{data\_alignment\_factor}.
2765 This operation
2766 is valid only if the current CFA rule is defined to use a
2767 register and offset.
2768
2769 \item \textbf{\DWCFAdefcfaexpressionTARG} \\
2770 The \DWCFAdefcfaexpressionNAME{} instruction takes a 
2771 \addtoindexx{exprloc class}
2772 single operand encoded as a 
2773 \DWFORMexprloc{} value representing a
2774 DWARF expression. The required action is to establish that
2775 expression as the means by which the current CFA is computed.
2776
2777 \textit{See Section \refersec{chap:callframeinstructions} 
2778 regarding restrictions on the DWARF
2779 expression operators that can be used.}
2780
2781 \end{enumerate}
2782
2783 \needlines{8}
2784 \subsubsection{Register Rule Instructions}
2785 \label{chap:registerruleinstructions}
2786 \begin{enumerate}[1. ]
2787
2788 \item \textbf{\DWCFAundefinedTARG} \\
2789 The \DWCFAundefinedNAME{} instruction takes a single unsigned
2790 LEB128\addtoindexx{LEB128!unsigned} operand that represents a register number. The required
2791 action is to set the rule for the specified register to
2792 \doublequote{undefined.}
2793
2794 \item \textbf{\DWCFAsamevalueTARG} \\
2795 The \DWCFAsamevalueNAME{} instruction takes a single unsigned
2796 LEB128 operand\addtoindexx{LEB128!unsigned} that represents a register number. The required
2797 action is to set the rule for the specified register to
2798 \doublequote{same value.}
2799
2800 \item \textbf{\DWCFAoffsetTARG} \\
2801 The \DWCFAoffsetNAME{} instruction takes two operands: a register
2802 number (encoded with the opcode) and an unsigned LEB128\addtoindexx{LEB128!unsigned}
2803 constant representing a factored offset. The required action
2804 is to change the rule for the register indicated by the
2805 register number to be an offset(N) rule where the value of
2806 N is 
2807 \textit{factored offset} * \addttindex{data\_alignment\_factor}.
2808
2809 \needlines{4}
2810 \item \textbf{\DWCFAoffsetextendedTARG} \\
2811 The \DWCFAoffsetextendedNAME{} 
2812 instruction takes two unsigned LEB128\addtoindexx{LEB128!unsigned} 
2813 operands representing a register number and a factored
2814 offset. This instruction is identical to
2815 \DWCFAoffset{} 
2816 except for the encoding and size of the register operand.
2817
2818 \needlines{6}
2819 \item \textbf{\DWCFAoffsetextendedsfTARG} \\
2820 The \DWCFAoffsetextendedsfNAME{} 
2821 instruction takes two operands:
2822 an unsigned LEB128\addtoindexx{LEB128!unsigned} 
2823 value representing a register number and a
2824 signed LEB128 factored offset. This instruction is identical
2825 to \DWCFAoffsetextended{} 
2826 except that the second operand is
2827 signed and factored. The resulting offset is 
2828 \textit{factored\_offset} * \addttindex{data\_alignment\_factor}.
2829
2830 \needlines{4}
2831 \item \textbf{\DWCFAvaloffsetTARG} \\
2832 The \DWCFAvaloffsetNAME{} 
2833 instruction takes two unsigned
2834 LEB128 operands\addtoindexx{LEB128!unsigned} representing a register number and a
2835 factored offset. The required action is to change the rule
2836 for the register indicated by the register number to be a
2837 val\_offset(N) rule where the value of N is 
2838 \textit{factored\_offset} * \addttindex{data\_alignment\_factor}.
2839
2840 \needlines{6}
2841 \item \textbf{\DWCFAvaloffsetsfTARG} \\
2842 The \DWCFAvaloffsetsfNAME{} instruction takes two operands: an
2843 unsigned LEB128\addtoindexx{LEB128!unsigned} value representing a register number and a
2844 signed LEB128\addtoindexx{LEB128!signed} factored offset. This instruction is identical
2845 to \DWCFAvaloffset{} except that the second operand is signed
2846 and factored. The resulting offset is 
2847 \textit{factored\_offset} * \addttindex{data\_alignment\_factor}.
2848
2849 \item \textbf{\DWCFAregisterTARG} \\
2850 The \DWCFAregisterNAME{} 
2851 instruction takes two unsigned LEB128\addtoindexx{LEB128!unsigned}
2852 operands representing register numbers. The required action
2853 is to set the rule for the first register to be register(R)
2854 where R is the second register.
2855
2856 \item \textbf{\DWCFAexpressionTARG} \\
2857 The \DWCFAexpressionNAME{} instruction takes two operands: an
2858 unsigned LEB128\addtoindexx{LEB128!unsigned} 
2859 value representing a register number, and
2860 a \DWFORMblock{} 
2861 value representing a DWARF expression. 
2862 The
2863 required action is to change the rule for the register
2864 indicated by the register number to be an expression(E)
2865 rule where E is the DWARF expression. That is, the DWARF
2866 expression computes the address. The value of the CFA is
2867 pushed on the DWARF evaluation stack prior to execution of
2868 the DWARF expression.
2869
2870 \textit{See Section \refersec{chap:callframeinstructions} 
2871 regarding restrictions on the DWARF
2872 expression operators that can be used.}
2873
2874 \needlines{7}
2875 \item \textbf{\DWCFAvalexpressionTARG} \\
2876 The \DWCFAvalexpressionNAME{} instruction takes two operands:
2877 an unsigned LEB128\addtoindexx{LEB128!unsigned} 
2878 value representing a register number, and
2879 a \DWFORMblock{} 
2880 value representing a DWARF expression. The
2881 required action is to change the rule for the register
2882 indicated by the register number to be a val\_expression(E)
2883 rule where E is the DWARF expression. That is, the DWARF
2884 expression computes the value of the given register. The value
2885 of the CFA is pushed on the DWARF evaluation stack prior to
2886 execution of the DWARF expression.
2887
2888 \textit{See Section \refersec{chap:callframeinstructions} 
2889 regarding restrictions on the DWARF
2890 expression operators that can be used.}
2891
2892 \needlines{6}
2893 \item \textbf{\DWCFArestoreTARG} \\
2894 The \DWCFArestoreNAME{} instruction takes a single operand (encoded
2895 with the opcode) that represents a register number. The
2896 required action is to change the rule for the indicated
2897 register to the rule assigned it by the \texttt{initial\_instructions}
2898 in the CIE.
2899
2900 \needlines{5}
2901 \item \textbf{\DWCFArestoreextendedTARG} \\
2902 The \DWCFArestoreextendedNAME{}
2903 instruction takes a single unsigned LEB128\addtoindexx{LEB128!unsigned} 
2904 operand that represents a register number. This
2905 instruction is identical to \DWCFArestore{} except for the
2906 encoding and size of the register operand.
2907
2908 \end{enumerate}
2909
2910 \subsubsection{Row State Instructions}
2911 \label{chap:rowstateinstructions}
2912
2913 \textit{The next two instructions provide the ability to stack and
2914 retrieve complete register states. They may be useful, for
2915 example, for a compiler that moves \addtoindex{epilogue} code 
2916 into the
2917 body of a function.}
2918
2919
2920 \begin{enumerate}[1. ]
2921
2922 \item \textbf{\DWCFArememberstateTARG} \\
2923 The \DWCFArememberstateNAME{} instruction takes no operands. The
2924 required action is to push the set of rules for every register
2925 onto an implicit stack.
2926
2927 \needlines{4}
2928 \item \textbf{\DWCFArestorestateTARG} \\
2929 The \DWCFArestorestateNAME{} instruction takes no operands. The
2930 required action is to pop the set of rules off the implicit
2931 stack and place them in the current row.
2932
2933 \end{enumerate}
2934
2935 \subsubsection{Padding Instruction}
2936 \label{chap:paddinginstruction}
2937 \begin{enumerate}[1. ]
2938 \item \textbf{\DWCFAnopTARG} \\
2939 The \DWCFAnopNAME{} instruction has no operands and no required
2940 actions. It is used as padding to make a CIE or FDE an
2941 appropriate size.
2942
2943 \end{enumerate}
2944
2945 \subsection{Call Frame Instruction Usage} 
2946 \label{chap:callframeinstructionusage}
2947
2948 \textit{To determine the virtual unwind rule set for a given location
2949 (L1), 
2950 \bb
2951 search 
2952 \eb
2953 through the FDE headers looking at the
2954 \HFNinitiallocation{} and \HFNaddressrange{} values to see if L1 is
2955 contained in the FDE. If so, then:}
2956 \begin{enumerate}[1. ]
2957
2958 \item \textit{Initialize a register set by reading the
2959 \HFNinitialinstructions{} field of the associated CIE.
2960 \bb
2961 Set L2 to the value of the \HFNinitiallocation{} field from the FDE header.
2962 \eb}
2963
2964
2965 \item \textit{Read and process the FDE's instruction
2966 sequence until a \DWCFAadvanceloc, 
2967 \DWCFAsetloc, or the
2968 end of the instruction stream is encountered.}
2969
2970 \item \textit{ If a \DWCFAadvanceloc{} or \DWCFAsetloc{}
2971 instruction is encountered, then compute a new location value
2972 (L2). If L1 $\geq$ L2 then process the instruction and go back
2973 to step 2.}
2974
2975 \needlines{6}
2976 \item \textit{ The end of the instruction stream can be thought
2977 of as a \DWCFAsetloc{} (\addttindex{initial\_location} + \addttindex{address\_range})
2978 instruction. Note that the FDE is ill-formed if L2 is less
2979 than L1.}
2980
2981 \end{enumerate}
2982
2983 \textit{The rules in the register set now apply to location L1.}
2984
2985 \textit{For an example, see 
2986 Appendix \refersec{app:callframeinformationexample}.}
2987
2988
2989
2990 \subsection{Call Frame Calling Address}
2991 \label{chap:callframecallingaddress}
2992
2993 \textit{When 
2994 virtually unwinding frames, consumers frequently wish to obtain 
2995 the address of the instruction which called a subroutine. This
2996 information is not always provided. Typically, however,
2997 one of the registers in the virtual unwind table is the
2998 Return Address.}
2999
3000 If a Return Address register is defined in the virtual
3001 unwind table, and its rule is undefined (for example, by
3002 \DWCFAundefined), then there is no return address and no
3003 call address, and the virtual unwind of stack activations
3004 \addtoindexx{activation of call frame}
3005 is complete.
3006
3007 \textit{In most cases the return address is in the same context as the
3008 calling address, but that need not be the case, especially if
3009 the producer knows in some way the call never will return. The
3010 context of the 'return address' might be on a different line,
3011 in a different lexical \livelink{chap:lexicalblock}{block}, 
3012 or past the end of the calling
3013 subroutine. If a consumer were to assume that it was in the
3014 same context as the calling address, the 
3015 virtual unwind might fail.}
3016
3017 \needlines{5}
3018 \textit{For architectures with constant-length instructions where
3019 the return address immediately follows the call instruction,
3020 a simple solution is to subtract the length of an instruction
3021 from the return address to obtain the calling instruction. For
3022 architectures with variable-length instructions (for example, x86),
3023 this is not possible. However, subtracting 1 from the return
3024 address, although not guaranteed to provide the exact calling
3025 address, generally will produce an address within the same
3026 context as the calling address, and that usually is sufficient.}
3027
3028
3029