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