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