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