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