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