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