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