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.
8 In the descriptions that follow, these terms are used to
9 specify the representation of DWARF sections:
12 \HFTinitiallength{}, \HFTsectionoffset{} and
13 \HFTsectionlength{}, which are
15 Sections \refersec{datarep:initiallengthvalues} and
16 \refersec{datarep:32bitand64bitdwarfformats}.
23 Section \refersec{datarep:integerrepresentationnames}.
26 \section{Accelerated Access}
27 \label{chap:acceleratedaccess}
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.}
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.}
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.}
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.
68 \subsection{Lookup by Name}
69 \addtoindexx{lookup!by name}
70 \addtoindexx{accelerated access!by name}
71 For lookup by name, a name index is maintained in a separate
72 object file section named \dotdebugnames{}.
74 \textit{The \dotdebugnames{} section is new in \DWARFVersionV,
75 and supersedes the \dotdebugpubnames{} and \dotdebugpubtypes{}
76 sections of earlier DWARF versions. While \dotdebugnames{} and
77 either \dotdebugpubnames{} and/or \dotdebugpubtypes{} sections
78 cannot both occur in the same compilation unit, both may be
79 found in the set of units that make up an executable or shared
83 primarily of two parts: a list of names, and a list of index
84 entries. A name, such as a subprogram name, type name, or
85 variable name, may have several defining declarations in the
86 debugging information. In this case, the entry for that name in
87 the list of names will refer to a sequence of index entries in
88 the second part of the table, each corresponding to one defining
89 declaration in the \dotdebuginfo{} section.
91 The name index may also contain an optional hash table for faster
94 A relocatable object file may contain a "per-CU" index, which
95 provides an index to the names defined in that compilation
98 An executable or shareable object file may contain either a collection of
99 "per-CU" indexes, simply copied from each relocatable object
100 file, or the linker may produce a "per-module" index by
101 combining the per-CU indexes into a single index that covers
102 the entire load module.
104 \subsubsection{Contents of the Name Index}
105 \label{chap:contentsofthenameindex}
106 The name index must contain an entry for each
107 debugging information entry that defines a
108 named subprogram, label, variable, type, or namespace,
109 subject to the following rules:
112 \item All non-defining declarations (that is,
113 debugging information entries with a
114 \DWATdeclaration{} attribute) are excluded.
116 \item \DWTAGnamespace{} debugging information entries
117 without a \DWATname{} attribute are
118 included with the name
119 \doublequote{\texttt{(anonymous namespace)}}.
121 \item All other debugging information entries
122 without a \DWATname{} attribute are excluded.
124 \item \DWTAGsubprogram{}, \DWTAGinlinedsubroutine{}, and
125 \DWTAGlabel{} debugging information entries
126 without an address attribute (\DWATlowpc{},
127 \DWAThighpc{}, \DWATranges{}, or \DWATentrypc{})
130 \item \DWTAGvariable{} debugging information entries
131 with a \DWATlocation{} attribute that includes a
132 \DWOPaddr{} or \DWOPformtlsaddress{} operator are
133 included; otherwise, they are excluded.
135 \item If a subprogram or inlined subroutine is included, and has a
136 \DWATlinkagename{} attribute, there will be an additional
137 index entry for the linkage name.
141 For the purposes of determining whether a
142 debugging information entry has a particular
143 attribute (such as \DWATname{}), if
144 debugging information entry $A$ has a \DWATspecification{}
145 or \DWATabstractorigin{} attribute pointing to another
146 debugging information entry $B$, any
147 attributes of $B$ are considered to be part of $A$.
149 \textit{The intent of the above rules is to provide the consumer with
150 some assurance that looking up an unqualified name in the index
151 will yield all relevant debugging information entries
152 that provide a defining declaration
153 at global scope for that name.}
155 \textit{A producer may choose to implement additional rules for what
156 names are placed in the index, and may communicate those rules to
157 a cooperating consumer via an augmentation string, described
161 \subsubsection{Structure of the Name Index}
162 \label{chap:structureofthenametindex}
163 Logically, the name index can be viewed as a list of names,
164 with a list of index entries for each name. Each index entry
165 corresponds to a debugging information entry
166 that matches the criteria given in the previous section. For
167 example, if one compilation unit has a function named \texttt{fred}
168 and another has a struct named \texttt{fred}, a lookup for
169 \doublequote{fred} will find the list containing those two index
172 The index section contains eight individual parts, as illustrated in
173 Figure \referfol{fig:nameindexlayoutpart1}.
175 \item A header, describing the layout of the section.
177 \item A list of compile units (CUs) referenced by this index.
179 \item A list of local type units (TUs) referenced by this index
180 that are present in this object file.
182 \item A list of foreign type units (TUs) referenced by this index
183 that are not present in this object file (that is, that have
184 been placed in a \splitDWARFobjectfile{} as described in
185 \refersec{datarep:splitdwarfobjectfiles}).
187 \item An optional hash lookup table.
189 \item The name table.
191 \item An abbreviations table, similar to the one used by the
192 \dotdebuginfo{} section.
194 \item The entry pool, containing a list of index entries for each
195 name in the name list.
201 %\includegraphics[keepaspectratio=true,scale=1.0]{name-index-drawings-6p1}
204 every node/.style={node font=\small, anchor=north west, text height=.8em, text depth=.2em, inner sep=4pt, outer ysep=0},
205 caption/.style={node font=\small \bfseries, text width=90pt},
206 overview/.style={draw, node font=\small, minimum height=28pt, text width=80pt},
207 detail1/.style={draw, minimum height=14pt, text width=116pt},
208 detail2/.style={draw, minimum height=28pt, text width=116pt},
209 detail3/.style={draw, minimum height=48pt, text width=116pt},
210 detail4/.style={draw, minimum height=72pt, text width=116pt},
211 ellip/.style={draw, shape=broken rectangle, minimum height=14pt, text width=116pt},
212 explode/.style={draw=black!50, fill=black!20, line join=bevel},
213 header/.style={fill=headerblue},
214 culist/.style={fill=cutuyellow},
215 buckets/.style={fill=bucketsblue},
216 hashes/.style={fill=hashesgreen},
217 stroffsets/.style={fill=stroffsetspink},
218 entryoffsets/.style={fill=entryoffsetspink},
219 indexentries/.style={fill=indexentriesorange}
222 % Name Table Overview
224 \begin{scope}[start chain=going below, node distance=0]
225 \node [on chain,caption] {Name Index};
226 \node (header) [on chain,overview,header] {Header};
227 \node (culist) [on chain,overview,header] {CU List};
228 \node (ltulist) [on chain,overview,header] {Local TU List};
229 \node (ftulist) [on chain,overview,header] {Foreign TU List};
230 \node (hash) [on chain,overview,header] {Hash Table};
231 \node (names) [on chain,overview,header] {Name Table};
232 \node (abbrev) [on chain,overview,header] {Abbrev Table};
233 \node (pool) [on chain,overview,header] {Entry Pool};
236 % Exploded View of CU List
238 \begin{scope}[start chain=going below, node distance=0, shift={($(header.north east) + (72pt,18pt)$)}]
239 \node (cu0) [on chain,detail1,culist] {offset to CU 0};
240 \node (cu1) [on chain,detail1,culist] {offset to CU 1};
241 \node (cu2) [on chain,ellip,culist] {\dots};
242 \node (cu3) [on chain,detail1,culist] {offset to CU $k - 1$};
245 \begin{scope}[on background layer]
246 \filldraw [explode] (culist.north east) -- (cu0.north west) -- (cu3.south west) -- (culist.south east) -- cycle;
249 \path [decoration={brace,amplitude=6pt}] ([xshift=9pt]cu0.north east)
250 [draw,decorate] -- ([xshift=9pt]cu3.south east)
251 node [midway,right,inner xsep=9pt] {\texttt{comp\_unit\_count} $(= k)$};
253 % Exploded View of Local TU List
255 \begin{scope}[start chain=going below, node distance=0, shift={($(cu3.south west) + (0,-9pt)$)}]
256 \node (ltu0) [on chain,detail1,culist] {offset to TU 0};
257 \node (ltu1) [on chain,detail1,culist] {offset to TU 1};
258 \node (ltu2) [on chain,ellip,culist] {\dots};
259 \node (ltu3) [on chain,detail1,culist] {offset to TU $t - 1$};
262 \begin{scope}[on background layer]
263 \filldraw [explode] (ltulist.north east) -- (ltu0.north west) -- (ltu3.south west) -- (ltulist.south east) -- cycle;
266 \path [decoration={brace,amplitude=6pt}] ([xshift=9pt]ltu0.north east)
267 [draw,decorate] -- ([xshift=9pt]ltu3.south east)
268 node [midway,right,inner xsep=9pt] {\texttt{local\_type\_unit\_count} $(= t)$};
270 % Exploded View of Foreign TU List
272 \begin{scope}[start chain=going below, node distance=0, shift={($(ltu3.south west) + (0,-9pt)$)}]
273 \node (ftu0) [on chain,detail1,culist] {signature of TU $t$};
274 \node (ftu1) [on chain,detail1,culist] {signature of TU $t + 1$};
275 \node (ftu2) [on chain,ellip,culist] {\dots};
276 \node (ftu3) [on chain,detail1,culist] {signature of TU $t + f - 1$};
279 \begin{scope}[on background layer]
280 \filldraw [explode] (ftulist.north east) -- (ftu0.north west) -- (ftu3.south west) -- (ftulist.south east) -- cycle;
283 \path [decoration={brace,amplitude=6pt}] ([xshift=9pt]ftu0.north east)
284 [draw,decorate] -- ([xshift=9pt]ftu3.south east)
285 node [midway,right,inner xsep=9pt] {\texttt{foreign\_type\_unit\_count} $(= f)$};
287 % Exploded View of Hash Table
289 \begin{scope}[start chain=going below, node distance=0, shift={($(ftu3.south west) + (0,-9pt)$)}]
290 \node (hash0) [on chain,detail2,buckets] {Buckets};
291 \node (hash1) [on chain,detail3,hashes] {Hashes};
294 \begin{scope}[on background layer]
295 \filldraw [explode] (hash.north east) -- (hash0.north west) -- (hash1.south west) -- (hash.south east) -- cycle;
298 % Exploded View of Name Table
300 \begin{scope}[start chain=going below, node distance=0, shift={($(hash1.south west) + (0,-9pt)$)}]
301 \node (name0) [on chain,detail3,stroffsets] {String Offsets};
302 \node (name1) [on chain,detail3,entryoffsets] {Entry Offsets};
305 \begin{scope}[on background layer]
306 \filldraw [explode] (names.north east) -- (name0.north west) -- (name1.south west) -- (names.south east) -- cycle;
309 % Exploded View of Entry Pool
311 \begin{scope}[shift={($(name1.south west) + (0,-9pt)$)}]
312 \node (pool0) [detail4,indexentries] {Index Entries};
315 \begin{scope}[on background layer]
316 \filldraw [explode] (pool.north east) -- (pool0.north west) -- (pool0.south west) -- (pool.south east) -- cycle;
320 \path [decoration={brace,amplitude=6pt}] ([xshift=9pt]hash0.north east)
321 [draw,decorate] -- ([xshift=9pt]pool0.south east)
322 node [midway,right,inner xsep=9pt] {\textit{see figure part 2 on next page}};
324 % Arrows pointing to .debug_info
326 \begin{scope}[shift={($(cu0.north east) + (15pt,27pt)$)}]
327 \node (debuginfo) {\textit{.debug\_info}};
330 \path ([xshift=28pt]cu0.center) coordinate (p1);
331 \path ([xshift=14pt]p1) coordinate (c1);
332 \path ([yshift=2pt]debuginfo.west) coordinate (p2);
333 \path ([xshift=-14pt]p2) coordinate (c2);
334 \draw [dashed,{Circle[open]}-{Stealth[]}] (p1) .. controls (c1) and (c2) .. (p2);
336 \path ([xshift=28pt]ltu0.center) coordinate (p3);
337 \path ([xshift=60pt]p3) coordinate (c3);
338 \path ([yshift=-2pt]debuginfo.west) coordinate (p4);
339 \path ([shift={(-21pt,-7pt)}]p4) coordinate (c4);
340 \draw [dashed,{Circle[open]}-{Stealth[]}] (p3) .. controls (c3) and (c4) .. (p4);
344 \caption{Name Index Layout}
345 \label{fig:nameindexlayoutpart1}
352 %\includegraphics[keepaspectratio=true,scale=1.0]{name-index-drawings-6p2}
355 every node/.style={node font=\small, anchor=north west, text height=.8em, text depth=.2em, inner sep=4pt, outer ysep=0},
356 % This diagram has a couple of two-line captions, so set the text depth
357 % to make room for the second line.
358 caption1/.style={node font=\small \bfseries, text depth=1.2em, text width=90pt},
359 caption2/.style={node font=\small \bfseries, text depth=1.2em, text width=41pt},
360 detail1/.style={draw, minimum height=14pt, text width=90pt},
361 detail2/.style={draw, minimum height=14pt, text width=41pt},
362 ellip1/.style={draw, shape=broken rectangle, minimum height=14pt, text width=90pt},
363 ellip2/.style={draw, shape=broken rectangle, minimum height=14pt, text width=41pt},
364 buckets/.style={fill=bucketsblue},
365 hashes/.style={fill=hashesgreen},
366 stroffsets/.style={fill=stroffsetspink},
367 entryoffsets/.style={fill=entryoffsetspink}
372 \begin{scope}[start chain=going below, node distance=0]
373 \node [on chain,caption1] {\\ Buckets};
374 \node (bucket0) [on chain,detail1,buckets] {bucket 0};
375 \node (bucket1) [on chain,detail1,buckets] {bucket 1};
376 \node (bucket2) [on chain,ellip1,buckets] {\dots};
377 \node (bucket3) [on chain,detail1,buckets] {bucket $b - 1$};
380 \path [decoration={brace,amplitude=6pt}] ([xshift=40pt]bucket0.north east)
381 [draw,decorate] -- ([xshift=40pt]bucket3.south east)
382 node [midway,right,inner xsep=9pt] {\texttt{bucket\_count} $(= b)$};
386 \begin{scope}[start chain=going below, node distance=0, shift={($(bucket3.south east) + (18pt,-24pt)$)}]
387 \node (hashes) [on chain,caption1] {\\ Hashes};
388 \node (hash0) [on chain,detail1,hashes] {hash value 1};
389 \node (hash1) [on chain,detail1,hashes] {hash value 2};
390 \node (hash2) [on chain,detail1,hashes] {hash value 3};
391 \node (hash3) [on chain,detail1,hashes] {hash value 4};
392 \node (hash4) [on chain,detail1,hashes] {hash value 5};
393 \node (hash5) [on chain,ellip1,hashes] {\dots};
394 \node (hash6) [on chain,detail1,hashes] {hash value $n$};
399 \begin{scope}[start chain=going below, node distance=0, shift={($(hashes.north east)$)}]
400 \node (strs) [on chain,caption2] {String \\ Offsets};
401 \node (str0) [on chain,detail2,stroffsets] {};
402 \node (str1) [on chain,detail2,stroffsets] {};
403 \node (str2) [on chain,detail2,stroffsets] {};
404 \node (str3) [on chain,detail2,stroffsets] {};
405 \node (str4) [on chain,detail2,stroffsets] {};
406 \node (str5) [on chain,ellip2,stroffsets] {};
407 \node (str6) [on chain,detail2,stroffsets] {};
412 \begin{scope}[start chain=going below, node distance=0, shift={($(strs.north east)$)}]
413 \node (entries) [on chain,caption2] {Entry \\ Offsets};
414 \node (entry0) [on chain,detail2,entryoffsets] {};
415 \node (entry1) [on chain,detail2,entryoffsets] {};
416 \node (entry2) [on chain,detail2,entryoffsets] {};
417 \node (entry3) [on chain,detail2,entryoffsets] {};
418 \node (entry4) [on chain,detail2,entryoffsets] {};
419 \node (entry5) [on chain,ellip2,entryoffsets] {};
420 \node (entry6) [on chain,detail2,entryoffsets] {};
423 \path [decoration={brace,amplitude=6pt}] ([xshift=9pt]entry0.north east)
424 [draw,decorate] -- ([xshift=9pt]entry6.south east)
425 node [midway,right,inner xsep=9pt] {\begin{tabular}{c}
426 \texttt{name\_count} \\
430 % Arrows pointing to .debug_str and entry pool
432 \path (str0.center) coordinate (p1);
433 \path ([xshift=18pt]p1) coordinate (c1);
434 \path ([shift={(36pt,45pt)}]p1) coordinate (p2);
435 \path ([xshift=-18pt]p2) coordinate (c2);
436 \draw [dashed,{Circle[open]}-{Stealth[]}] (p1) .. controls (c1) and (c2) .. (p2) node [anchor=west] {$.debug\_str$};
438 \path (entry0.center) coordinate (p3);
439 \path ([xshift=18pt]p3) coordinate (c3);
440 \path ([shift={(36pt,27pt)}]p3) coordinate (p4);
441 \path ([xshift=-18pt]p4) coordinate (c4);
442 \draw [dashed,{Circle[open]}-{Stealth[]}] (p3) .. controls (c3) and (c4) .. (p4) node [anchor=west] {$entry\ pool$};
444 % Arrows from buckets to hashes
446 \path ([xshift=24pt]bucket0.center) coordinate (p5);
447 \path ([xshift=130pt]p5) coordinate (c5);
448 \path ([xshift=-70pt]hash0.west) coordinate (c6);
449 \draw [dashed,{Circle[open]}-{Stealth[]}] (p5) .. controls (c5) and (c6) .. (hash0.west);
451 \path ([xshift=24pt]bucket1.center) coordinate (p7);
452 \path ([xshift=120pt]p7) coordinate (c7);
453 \path ([xshift=-144pt]hash3.west) coordinate (c8);
454 \draw [dashed,{Circle[open]}-{Stealth[]}] (p7) .. controls (c7) and (c8) .. (hash3.west);
460 %\includegraphics[keepaspectratio=true,scale=1.0]{name-index-drawings-6p3}
462 every node/.style={node font=\small, anchor=north west, text height=.8em, text depth=.2em, inner sep=4pt, outer ysep=0},
463 caption/.style={node font=\small \bfseries, text width=120pt},
464 detail/.style={draw, node font=\small, minimum height=14pt, text width=120pt},
465 ellip/.style={draw, shape=broken rectangle, minimum height=14pt, text width=120pt},
466 explode/.style={draw=black!50, fill=black!20, line join=bevel},
467 indexentries/.style={fill=indexentriesorange}
472 \begin{scope}[start chain=going below, node distance=0]
473 \node [on chain,caption] {Entry Pool};
474 \node (entry0) [on chain,detail,indexentries] {index entry \#1 for ``a''};
475 \node (entry1) [on chain,detail,indexentries] {index entry \#2 for ``a''};
476 \node (entry2) [on chain,ellip,indexentries] {\dots};
477 \node (entry3) [on chain,detail,indexentries] {0 \textit{(end of entries for ``a'')}};
478 \node (entry4) [on chain,detail,indexentries] {index entry \#1 for ``b''};
479 \node (entry5) [on chain,detail,indexentries] {index entry \#2 for ``b''};
480 \node (entry6) [on chain,ellip,indexentries] {\dots};
481 \node (entry7) [on chain,detail,indexentries] {0};
482 \node (entry8) [on chain,detail,indexentries] {index entry \#1 for ``c''};
483 \node (entry9) [on chain,ellip,indexentries] {\dots};
486 % Exploded Index Entry
488 \begin{scope}[start chain=going below, node distance=0, shift={($(entry1.north east) + (60pt,30pt)$)}]
489 \node (abbrev) [on chain,detail,indexentries] {abbrev code};
490 \node (attr1) [on chain,detail,indexentries] {attribute};
491 \node (attr2) [on chain,detail,indexentries] {attribute};
492 \node (attr3) [on chain,ellip,indexentries] {\dots};
493 \node (attr4) [on chain,detail,indexentries] {attribute};
496 \begin{scope}[on background layer]
497 \filldraw [explode] (entry1.north east) -- (abbrev.north west) -- (attr4.south west) -- (entry1.south east) -- cycle;
502 \node (from1) [anchor=east] at ([xshift=-36pt]entry0.west) {\textit{(from name table)}};
503 \draw [dashed,-{Stealth[]}] (from1) -- (entry0.west);
505 \node (from2) [anchor=east] at ([xshift=-36pt]entry4.west) {\textit{(from name table)}};
506 \draw [dashed,-{Stealth[]}] (from2) -- (entry4.west);
508 \node (from2) [anchor=east] at ([xshift=-36pt]entry7.west) {\textit{(from name table)}};
509 \draw [dashed,-{Stealth[]}] (from2) -- (entry7.west);
514 %\caption{Name Index Layout \textit{(concluded)}}
515 Figure~\ref{fig:nameindexlayoutpart1}: Name Index Layout \textit{(concluded)}
516 %\label{fig:nameindexlayoutpart2}
520 The formats of the header and the hash lookup table are described
521 in Section \refersec{chap:datarepresentationofthenameindex}.
523 The list of CUs and the list of local TUs are each an array of
524 offsets, each of which is the offset of a compile unit or a type unit
525 in the \dotdebuginfo{} section. For a per-CU index, there is a single CU
526 entry, and there may be a TU entry for each type unit generated in the
527 same translation unit as the single CU. For a per-module index, there
528 will be one CU entry for each compile unit in the module, and one TU
529 entry for each unique type unit in the module. Each list is indexed
532 The list of foreign TUs is an array of 64-bit (\DWFORMrefsigeight) type
533 signatures, representing types referenced by the index whose
534 definitions have been placed in a different object file (that is, a split
535 DWARF object). This list may be empty.
536 The foreign TU list immediately follows the local TU list
537 and they both use the same index, so that if there are $N$ local TU entries,
538 the index for the first foreign TU is $N$.
540 The name table is logically a table with a row for each unique name in
541 the index, and two columns. The first column contains a reference to
542 the name, as a string. The second column contains the offset within
543 the entry pool of the list of index entries for the name.
546 The abbreviations table describes the formats of the entries in the
547 entry pool. Like the DWARF abbreviations table in the \dotdebugabbrev{}
548 section, it defines one or more abbreviation codes. Each abbreviation
549 code provides a DWARF tag value followed by a list of pairs that
550 defines an attribute and form code used by entries with that
553 The entry pool contains all the index entries, grouped by name. The
554 second column of the name list points to the first index entry for the
555 name, and all the index entries for that name are placed one after the
558 Each index entry begins with an unsigned LEB128 abbreviation code.
559 The abbreviation list for that code provides the DWARF tag value for
560 the entry as well as the set of attributes provided by the entry and
564 The standard attributes are:
566 \item Compilation Unit (CU), a reference to an entry in the list of
567 CUs. In a per-CU index, index entries without this attribute
568 implicitly refer to the single CU.
570 \item Type Unit (TU), a reference to an entry in the list of local
573 \item Debugging information entry offset within the CU or TU.
575 \item Parent debugging information entry,
576 a reference to the index entry for the parent.
577 This is represented as the offset of the entry relative to
578 the start of the entry pool.
580 \item Type hash, an 8-byte hash of the type declaration.
585 It is possible that an indexed debugging information entry
586 has a parent that is not
587 indexed (for example, if its parent does not have a name attribute).
588 In such a case, a parent attribute may point to a nameless index
589 entry (that is, one that cannot be reached from any entry in the
590 name table), or it may point to the nearest ancestor that does
593 A producer may define additional vendor-specific attributes,
594 and a consumer will be able to ignore and skip over any attributes
595 it is not prepared to handle.
598 When an index entry refers to a foreign type unit, it may have
599 attributes for both CU and (foreign) TU. For such entries, the CU
600 attribute gives the consumer a reference to the CU that may be used to
601 locate a \splitDWARFobjectfile{} that contains the type unit.
603 \textit{The type hash attribute, not to be confused with the type signature
604 for a TU, may be provided for type entries whose declarations are not
605 in a type unit, for the convenience of link-time or post-link
606 utilities that wish to de-duplicate type declarations across
607 compilation units. The type hash, however, is computed by the
608 same method as specified for type signatures.}
610 The last entry for each name is followed by a zero byte that
611 terminates the list. There may be gaps between the lists.
613 \subsubsection{Per-CU versus Per-Module Indexes}
614 \label{chap:percuvspermoduleindexes}
615 \textit{In a per-CU index, the CU list may have only a single entry,
616 and index entries may omit the CU attribute. (Cross-module or link-time
617 optimization, however, may produce an object file with several compile
618 units in one object. A compiler in this case may produce a separate
619 index for each CU, or a combined index for all CUs. In the latter
620 case, index entries will require the CU attribute.) Most name table
621 entries may have only a single index entry for each, but sometimes a
622 name may be used in more than one context and will require multiple
623 index entries, each pointing to a different debugging information
626 \textit{When linking object files containing per-CU indexes, the
627 linker may choose to concatenate the indexes as ordinary sections,
628 or it may choose to combine the input indexes into a single
631 \textit{A per-module index will contain a number of CUs, and each index
632 entry contains a CU attribute or a TU attribute to identify which
633 CU or TU contains the debugging information entry being indexed. When a
634 given name is used in multiple CUs or TUs, it will typically have a
635 series of index entries pointing to each CU or TU where it is declared.
636 For example, an index entry for a \addtoindex{C++} namespace needs to
637 list each occurrence, since each CU may contribute additional names to
638 the namespace, and the consumer needs to find them all. On the
639 other hand, some index entries do not need to list more than one
640 definition; for example, with the one-definition rule in \addtoindex{C++},
641 duplicate entries for a function may be omitted, since the consumer
642 only needs to find one declaration. Likewise, a per-module index needs
643 to list only a single copy of a type declaration contained in a type
646 \textit{For the benefit of link-time or post-link utilities that consume
647 per-CU indexes and produce a per-module index, the per-CU index
648 entries provide the tag encoding for the original debugging
649 information entry, and may provide a type hash for certain types that
650 may benefit from de-duplication. For example, the standard declaration
651 of the typedef \texttt{uint32\_t} is likely to occur in many CUs, but a
652 combined per-module index needs to retain only one; a user declaration
653 of a typedef \texttt{mytype} may refer to a different type at each
654 occurrence, and a combined per-module index retains each unique
655 declaration of that type.}
658 \subsubsection{Data Representation of the Name Index}
659 \label{chap:datarepresentationofthenameindex}
660 The name index is placed in a section named \dotdebugnames, and
661 consists of the eight parts described in the following sections.
663 \subsubsubsection{Section Header}
664 The section header contains the following fields:
665 \begin{enumerate}[1. ]
666 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
667 \addttindexx{unit\_length}
668 The length of this contribution to the name index section,
669 not including the length field itself.
671 \item \texttt{version} (\HFTuhalf) \\
672 A version number\addtoindexx{version number!name index table}
673 (see Section \refersec{datarep:nameindextable}).
674 This number is specific to the name index table and is
675 independent of the DWARF version number.
677 \item \textit{padding} (\HFTuhalf) \\
678 Reserved to DWARF (must be zero).
680 \item \texttt{comp\_unit\_count} (\HFTuword) \\
681 The number of CUs in the CU list.
683 \item \texttt{local\_type\_unit\_count} (\HFTuword) \\
684 The number of TUs in the local TU list.
686 \item \texttt{foreign\_type\_unit\_count} (\HFTuword) \\
687 The number of TUs in the foreign TU list.
689 \item \texttt{bucket\_count} (\HFTuword) \\
690 The number of hash buckets in the hash lookup table.
691 If there is no hash lookup table, this field contains 0.
693 \item \texttt{name\_count} (\HFTuword) \\
694 The number of unique names in the index.
696 \item \texttt{abbrev\_table\_size} (\HFTuword) \\
697 The size in bytes of the abbreviations table.
699 \item \texttt{augmentation\_string\_size} (\HFTuword) \\
700 The size in bytes of the augmentation string. This value is
701 rounded up to a multiple of 4.
703 \item \texttt{augmentation\_string} (\HFTaugstring) \\
704 A vendor-specific augmentation string, which provides additional
705 information about the contents of this index. If provided, the string
706 begins with a 4-character vendor ID. The remainder of the
707 string is meant to be read by a cooperating consumer, and its
708 contents and interpretation are not specified here. The
709 string is padded with null characters to a multiple of
710 four bytes in length.
714 presence of an unrecognised augmentation string may make it impossible
715 for a consumer to process data in the \dotdebugnames{} section.
721 \subsubsubsection{List of CUs}
722 The list of CUs immediately follows the header. Each entry in the
723 list is an offset of the corresponding compilation unit
724 in the \dotdebuginfo{} section.
725 In the DWARF-32 format, a section offset is 4 bytes,
726 while in the DWARF-64 format, a section offset is 8 bytes.
728 The total number of entries in the list is given by \texttt{comp\_unit\_count}.
729 There must be at least one CU.
732 \subsubsubsection{List of Local TUs}
733 The list of local TUs immediately follows the list of CUs. Each
734 entry in the list is an offset of the corresponding type unit
735 in the \dotdebuginfo{} section.
736 In the DWARF-32 format, a section offset is 4 bytes,
737 while in the DWARF-64 format, a section offset is 8 bytes.
739 The total number of entries in the list is given by
740 \texttt{local\_type\_unit\_count}. This list may be empty.
742 \subsubsubsection{List of Foreign TUs}
743 The list of foreign TUs immediately follows the list of local TUs.
744 Each entry in the list is a 8-byte type signature (as described by
747 The number of entries in the list is given by \texttt{foreign\_type\_unit\_count}.
748 This list may be empty.
751 \subsubsubsection{Hash Lookup Table}
752 The optional hash lookup table immediately follows the list of type signatures.
754 The hash lookup table is actually two separate arrays: an array of
755 buckets, followed immediately by an array of hashes. The number of
756 entries in the buckets array is given by \texttt{bucket\_count}, and the number
757 of entries in the hashes array is given by \texttt{name\_count}. Each array
758 contains 4-byte unsigned integers.
761 Symbols are entered into the hash table by first computing a hash
762 value from the symbol name. The hash is computed
763 using the "DJB" hash function\addtoindexx{DJB hash function}
764 described in Section \refersec{datarep:nametablehashfunction}.
765 Given a hash value for the symbol,
766 the symbol is entered into a bucket whose index is the hash value
767 modulo \texttt{bucket\_count}. The buckets array is indexed starting at 0.
769 Each bucket contains the index of an entry in the hashes array. The
770 hashes array is indexed starting at 1, and an empty bucket is
771 represented by the value 0.
774 The hashes array contains a sequence of the full hash values for each
775 symbol. All symbols that have the same index into the bucket list
776 follow one another in the hashes array, and the indexed entry in
777 the bucket list refers to the first symbol.
778 When searching for a symbol, the search
779 starts at the index given by the bucket, and continues either until a
780 matching symbol is found or until a hash value from a different bucket
781 is found. If two different symbol names produce the same hash value,
782 that hash value will occur twice in the hashes array. Thus, if a
783 matching hash value is found, but the name does not match, the search
784 continues visiting subsequent entries in the hashes table.
786 When a matching hash value is found in the hashes array, the index of
787 that entry in the hashes array is used to find the corresponding entry
791 \subsubsubsection{Name Table}
792 The name table immediately follows the hash lookup table. The name
793 table is laid out in column-major order (that is, the first column,
794 followed by the second column). Each entry in the first column
795 contains the string table offset (\DWFORMstrp) of the name in the
796 \dotdebugstr{} (or \dotdebugstrdwo) section. Each entry in the second
797 column contains the offset (as a section offset) within the entry pool
798 of the list of index entries for the name. Rows in the name table are
799 indexed starting at 1 (to match the hashes array).
801 The number of rows in the name table is given by \texttt{name\_count}.
803 If there is a hash lookup table, the
804 row number of an entry in the name table must
805 match the row number of its corresponding entry in the hashes array.
807 If there is no hash lookup table, there is no ordering
808 requirement for the name table.
811 \subsubsubsection{Abbreviations Table}
812 The abbreviations table immediately follows the name table. This table
813 consists of a series of abbreviation declarations. Its size is given
814 by \texttt{abbrev\_table\_size}.
816 Each abbreviation declaration defines the tag and other attributes for
817 a particular form of index entry. Each declaration starts with an
818 unsigned LEB128 number representing the abbreviation code itself. It
819 is this code that appears at the beginning of an index entry. The
820 abbreviation code must not be 0.
822 The abbreviation code is followed by another unsigned LEB128 number
823 that encodes the tag of the debugging information entry corresponding
826 Following the tag encoding is a series of attribute specifications.
827 Each attribute consists of two parts: an unsigned LEB128 number that
828 represents the index attribute, and another unsigned LEB128 number
829 that represents the attribute's form (as described in
830 Section \refersec{datarep:attributeencodings}). The series of attribute
831 specifications ends with an entry containing 0 for the attribute and
834 The index attributes and their meanings are listed in
835 Table \referfol{tab:indexattributeencodings}.
838 \setlength{\extrarowheight}{0.1cm}
839 \begin{longtable}{l|l}
840 \caption{Index attribute encodings} \label{tab:indexattributeencodings}\\
841 \hline \bfseries Attribute name &\bfseries Meaning \\ \hline
843 \bfseries Attribute name &\bfseries Meaning \\ \hline
845 \hline \emph{Continued on next page}
849 \DWIDXcompileunitTARG & Index of CU \\
850 \DWIDXtypeunitTARG & Index of TU (\mbox{local} or foreign) \\
851 \DWIDXdieoffsetTARG & Offset of DIE within CU or TU \\
852 \DWIDXparentTARG & Index of name \mbox{table} entry for parent \\
853 \DWIDXtypehashTARG & Hash of type \mbox{declaration} \\
857 The abbreviations table ends with an entry consisting of a single 0
858 byte for the abbreviation code. The size of the table given by
859 \texttt{abbrev\_table\_size} may include optional padding following the
862 \subsubsubsection{Entry Pool}
863 The entry pool immediately follows the abbreviations table. The second
864 column of each row of the name table points to an offset in the entry
865 pool, where a series of index entries for that name is located.
868 Each index entry in the series begins with an abbreviation code, and is
869 followed by the attributes described by the abbreviation declaration
870 for that code. The last index entry in the series is followed by a
871 terminating entry whose abbreviation code is 0.
873 Gaps are not allowed between entries in a series (that is, the entries
874 for a single name must all be contiguous), but there may be gaps
877 \textit{For example, a producer/consumer combination may find
878 it useful to maintain alignment.}
880 The size of the entry pool is the remaining size of the contribution to
881 the index section, as defined by the \texttt{unit\_length} header field.
883 \subsection{Lookup by Address}
884 \label{chap:lookupbyaddress}
885 For \addtoindexx{lookup!by address}
886 lookup by address, a table is maintained in a separate
887 \addtoindexx{accelerated access!by address}
888 object file section called
889 \dotdebugaranges{}. The table consists
890 of sets of variable length entries, each set describing the
891 portion of the program\textquoteright{}s address space that is covered by
892 a single compilation unit.
895 Each set begins with a header containing five values:
896 \begin{enumerate}[1. ]
897 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
898 \addttindexx{unit\_length}
899 The length of this contribution to the address lookup section,
900 not including the length field itself.
902 \item \texttt{version} (\HFTuhalf) \\
903 A version number\addtoindexx{version number!address lookup table}
904 (see Section \refersec{datarep:addrssrangetable}).
905 This number is specific to the address lookup table and is
906 independent of the DWARF version number.
908 \item \texttt{debug\_info\_offset} (section offset) \\
910 \addtoindexx{section offset!in .debug\_aranges header}
911 beginning of the \dotdebuginfo{} section of the
912 compilation unit header referenced by the set.
914 \item \texttt{address\_size} (\HFTubyte) \\
915 The \addtoindex{size of an address}
917 \addttindexx{address\_size}
918 the target architecture. For
919 \addtoindexx{address space!segmented}
920 segmented addressing, this is
921 the size of the offset portion of the address.
923 \item \HFNsegmentselectorsize{} (\HFTubyte) \\
924 The size of a segment selector in
925 bytes on the target architecture. If the target system uses
926 a flat address space, this value is 0.
930 This header is followed by a variable number of address range
931 descriptors. Each descriptor is a triple consisting of a
932 segment selector, the beginning address within that segment
933 of a range of text or data covered by some entry owned by
934 the corresponding compilation unit, followed by the non-zero
935 length of that range. A particular set is terminated by an
936 entry consisting of three zeroes.
937 When the \HFNsegmentselectorsize{} value
938 is zero in the header, the segment selector is omitted so that
939 each descriptor is just a pair, including the terminating
940 entry. By scanning the table, a debugger can quickly decide
941 which compilation unit to look in to find the debugging
942 information for an object that has a given address.
944 \textit{If the range of addresses covered by the text and/or data
945 of a compilation unit is not contiguous, then there may be
946 multiple address range descriptors for that compilation unit.}
949 \section{Line Number Information}
950 \label{chap:linenumberinformation}
951 \textit{A source\dash level debugger needs to know how to
952 \addtoindexx{line number information|see{\textit{also} statement list attribute}}
953 associate locations in the source files with the corresponding
954 machine instruction addresses in the executable or the shared
955 object files used by that executable object file. Such an
956 association makes it possible for the debugger user
957 to specify machine instruction addresses in terms of source
958 locations. This is done by specifying the line number
959 and the source file containing the statement. The debugger
960 can also use this information to display locations in terms
961 of the source files and to single step from line to line,
962 or statement to statement.}
964 Line number information generated for a compilation unit is
966 \dotdebugline{} section of an object file, and optionally
967 also in the \dotdebuglinestr{} section, and
968 is referenced by a corresponding compilation unit debugging
970 (see Section \refersec{chap:fullandpartialcompilationunitentries})
971 in the \dotdebuginfo{} section.
973 \textit{Some computer architectures employ more than one instruction
974 set (for example, the ARM
975 \addtoindexx{ARM instruction set architecture}
977 MIPS architectures support
978 \addtoindexx{MIPS instruction set architecture}
979 a 32-bit as well as a 16-bit instruction set). Because the
980 instruction set is a function of the program counter, it is
981 convenient to encode the applicable instruction set in the
982 \dotdebugline{} section as well.}
984 \textit{If space were not a consideration, the information provided
985 in the \dotdebugline{}
986 section could be represented as a large
987 matrix, with one row for each instruction in the emitted
988 object code. The matrix would have columns for:}
990 \item \textit{the source file name}
991 \item \textit{the source line number}
992 \item \textit{the source column number}
993 \item \textit{whether this instruction is the beginning of a source statement}
994 \item \textit{whether this instruction is the beginning of a \addtoindex{basic block}}
995 \item \textit{and so on}
997 \textit{Such a matrix, however, would be impractically large. We
998 shrink it with two techniques. First, we delete from
999 the matrix each row whose file, line, source column and
1000 discriminator\addttindexx{discriminator}
1001 is identical with that of its
1002 predecessors. Any deleted row would never be the beginning of
1003 a source statement. Second, we design a byte-coded language
1004 for a state machine and store a stream of bytes in the object
1005 file instead of the matrix. This language can be much more
1006 compact than the matrix. To the line number information a
1007 consumer must \doublequote{run} the state machine
1008 to generate the matrix for each compilation unit of interest.
1009 The concept of an encoded matrix also leaves
1010 room for expansion. In the future, columns can be added to the
1011 matrix to encode other things that are related to individual
1012 instruction addresses.}
1015 \subsection{Definitions}
1016 \label{chap:definitions}
1017 The following terms are used in the description of the line
1018 number information format:
1020 \begin{longtable} {lP{9cm}}
1022 The hypothetical machine used by a consumer of the line number
1023 information to expand the byte\dash coded
1024 instruction stream into a matrix of
1025 line number information. \\
1027 line number program &
1028 A series of byte\dash coded
1029 line number information instructions representing
1030 one compilation unit. \\
1032 \addtoindex{basic block} &
1033 A sequence of instructions where only the first instruction may be a
1034 branch target and only the last instruction may transfer control. A
1035 subprogram invocation is defined to be an exit from a
1036 \addtoindex{basic block}.
1038 \textit{A \addtoindex{basic block} does not
1039 necessarily correspond to a specific source code
1043 A series of contiguous target machine instructions. One compilation unit
1044 may emit multiple sequences (that is, not all instructions within a
1045 compilation unit are assumed to be contiguous). \\
1049 \subsection{State Machine Registers}
1050 \label{chap:statemachineregisters}
1051 The line number information state machine has a number of
1052 registers as shown in Table \referfol{tab:statemachineregisters}.
1054 \begin{longtable}{l|P{9cm}}
1055 \caption{State machine registers } \label{tab:statemachineregisters} \\
1056 \hline \bfseries Register name&\bfseries Meaning\\ \hline
1058 \bfseries Register name&\bfseries Meaning\\ \hline
1060 \hline \emph{Continued on next page}
1064 \addtoindexi{\texttt{address}}{address register!in line number machine}&
1065 The program\dash counter value corresponding to a machine instruction
1066 generated by the compiler. \\
1068 \addttindex{op\_index} &
1069 An unsigned integer representing the index of an operation within a VLIW
1070 instruction. The index of the first operation is 0. For non-VLIW
1071 architectures, this register will always be 0. \\
1074 An unsigned integer indicating the identity of the source file
1075 corresponding to a machine instruction. \\
1078 An unsigned integer indicating a source line number. Lines are numbered
1079 beginning at 1. The compiler may emit the value 0 in cases where an
1080 instruction cannot be attributed to any source line. \\
1082 \addttindex{column} &
1083 An unsigned integer indicating a column number within a source line.
1084 Columns are numbered beginning at 1. The value 0 is reserved to indicate
1085 that a statement begins at the \doublequote{left edge} of the line. \\
1087 \addttindex{is\_stmt} &
1088 A boolean indicating that the current instruction is a recommended
1089 breakpoint location. A recommended breakpoint location
1090 is intended to \doublequote{represent} a line, a
1091 statement and/or a semantically distinct subpart of a
1094 \addttindex{basic\_block} &
1095 A boolean indicating that the current instruction is the beginning of a
1096 \addtoindex{basic block}. \\
1098 \addttindex{end\_sequence} &
1099 A boolean indicating that the current address is that of the first byte after
1100 the end of a sequence of target machine instructions.
1101 \addttindex{end\_sequence}
1102 terminates a sequence of lines; therefore other information in the same
1103 row is not meaningful. \\
1105 \addttindex{prologue\_end} &
1106 A boolean indicating that the current address is one (of possibly many)
1107 where execution should be suspended for a breakpoint at the entry of a
1110 \addttindex{epilogue\_begin} &
1111 A boolean indicating that the current address is one (of possibly many)
1112 where execution should be suspended for a breakpoint just prior to
1113 the exit of a function. \\
1116 An unsigned integer whose value encodes the applicable
1117 instruction set architecture for the current instruction.
1119 \textit{The encoding of instruction sets should be shared by all
1120 users of a given architecture. It is recommended that this
1121 encoding be defined by the ABI authoring committee for each
1124 \addttindex{discriminator} &
1125 An unsigned integer identifying the block to which the
1126 current instruction belongs. Discriminator values are assigned
1127 arbitrarily by the DWARF producer and serve to distinguish
1128 among multiple blocks that may all be associated with the
1129 same source file, line, and column. Where only one block
1130 exists for a given source position, the discriminator value
1134 The \texttt{address} and \addttindex{op\_index} registers,
1135 taken together, form an \addtoindex{operation pointer} that can
1136 reference any individual operation within the instruction stream.
1138 At the beginning of each sequence within a line number
1139 program, the state of the registers is as show in Table
1140 \refersec{tab:linenumberprograminitiastate}.
1142 \caption{Line number program initial state}
1143 \label{tab:linenumberprograminitiastate}
1145 \begin{tabular}{l|p{9.5cm}}
1147 \texttt{address} & 0 \\
1148 \addttindex{op\_index} & 0 \\
1149 \texttt{file} & 1 \\
1150 \texttt{line} & 1 \\
1151 \texttt{column} & 0 \\
1152 \addttindex{is\_stmt} & determined by \addttindex{default\_is\_stmt}
1153 in the line number program header \\
1154 \addttindex{basic\_block} & \doublequote{false} \addtoindexx{basic block} \\
1155 \addttindex{end\_sequence} & \doublequote{false} \\
1156 \addttindex{prologue\_end} & \doublequote{false} \\
1157 \addttindex{epilogue\_begin} & \doublequote{false} \\
1158 \addttindex{isa} & 0 \\
1159 \addttindex{discriminator} & 0 \\
1167 \addttindex{isa} value 0 specifies that the instruction set is the
1168 architecturally determined default instruction set. This may
1169 be fixed by the ABI, or it may be specified by other means,
1170 for example, by the object file description.}
1173 \subsection{Line Number Program Instructions}
1174 The state machine instructions in a line number program belong to one of three categories:
1176 \begin{enumerate}[1. ]
1177 \item special opcodes \\
1178 These have a \HFTubyte{} opcode field and no operands.\vspace{1ex}
1180 \textit{Most of the instructions in a
1181 line number program are special opcodes.}
1184 \item standard opcodes \\
1185 These have a \HFTubyte{} opcode field which may be followed by zero or more
1186 \addtoindex{LEB128} operands (except for
1187 \mbox{\DWLNSfixedadvancepc,} see
1188 Section \refersec{chap:standardopcodes}).
1189 The opcode implies the number of operands and their meanings, but the
1190 line number program header also specifies the number of operands for
1191 each standard opcode.
1194 \item extended opcodes \\
1195 These have a multiple byte format. The first byte is zero; the next bytes
1196 are an unsigned LEB128\addtoindexx{LEB128!unsigned} integer giving the number of bytes in the
1197 instruction itself (does not include the first zero byte or the size). The
1198 remaining bytes are the instruction itself (which begins with a \HFTubyte{}
1199 extended opcode). \\
1203 \subsection{The Line Number Program Header}
1204 \label{chap:linenumberprogramheader}
1205 The optimal encoding of line number information depends to a
1206 certain degree upon the architecture of the target machine. The
1207 line number program header provides information used by
1208 consumers in decoding the line number program instructions for
1209 a particular compilation unit and also provides information
1210 used throughout the rest of the line number program.
1212 The line number program for each compilation unit begins with
1213 a header containing the following fields in order:
1215 \begin{enumerate}[1. ]
1216 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
1217 \addttindexx{unit\_length}
1218 The size in bytes of the line number information for this
1219 compilation unit, not including the length field itself
1220 (see Section \refersec{datarep:initiallengthvalues}).
1223 \item \texttt{version} (\HFTuhalf) \\
1224 A version number\addtoindexx{version number!line number information}
1225 (see Section \refersec{datarep:linenumberinformation}).
1226 This number is specific to
1227 the line number information and is independent of the DWARF
1230 \item \texttt{address\_size} (\HFTubyte)\\
1231 A 1-byte unsigned integer containing the size in bytes of an
1232 address (or offset portion of an address for segmented addressing)
1233 on the target system.
1235 \textit{The \addttindex{address\_size} field is new in DWARF Version 5.
1236 It is needed to support the common practice of stripping all but
1237 the line number sections (\dotdebugline{} and \dotdebuglinestr{})
1238 from an executable.}
1240 \item \HFNsegmentselectorsize{} (\HFTubyte) \\
1241 A 1-byte unsigned integer containing the size in bytes of a segment
1242 selector on the target system.
1244 \textit{The \HFNsegmentselectorsize{} field is new in DWARF Version 5.
1245 It is needed in combination with the \addttindex{address\_size} field
1246 to accurately characterize the address representation on the target
1250 \item \texttt{header\_length} \\
1251 The number of bytes following the \addttindex{header\_length} field to the
1252 beginning of the first byte of the line number program itself.
1253 In the \thirtytwobitdwarfformat, this is a 4-byte unsigned
1254 length; in the \sixtyfourbitdwarfformat, this field is an
1255 8-byte unsigned length
1256 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1258 \item \texttt{minimum\_instruction\_length} (\HFTubyte) \\
1259 \addttindexx{minimum\_instruction\_length}
1260 The size in bytes of the smallest target machine
1261 instruction. Line number program opcodes that alter
1262 the \texttt{address} and \addttindex{op\_index}
1263 registers use this and
1264 \addttindex{maximum\_operations\_per\_instruction}
1265 in their calculations.
1268 \item \texttt{maximum\_operations\_per\_instruction} (\HFTubyte) \\
1270 \addttindexx{maximum\_operations\_per\_instruction}
1271 maximum number of individual operations that may be
1272 encoded in an instruction. Line number program opcodes
1273 that alter the \texttt{address} and
1274 \addttindex{op\_index} registers use this and
1275 \addttindex{minimum\_instruction\_length} in their calculations.
1278 architectures, this field is 1, the \addttindex{op\_index} register is always
1279 0, and the \addtoindex{operation pointer} is simply the \texttt{address} register.
1282 \item \texttt{default\_is\_stmt} (\HFTubyte) \\
1283 \addttindexx{default\_is\_stmt}
1284 The initial value of the \addttindex{is\_stmt} register.
1286 \textit{A simple approach
1287 to building line number information when machine instructions
1288 are emitted in an order corresponding to the source program
1289 is to set \addttindex{default\_is\_stmt}
1290 to \doublequote{true} and to not change the
1291 value of the \addttindex{is\_stmt} register
1292 within the line number program.
1293 One matrix entry is produced for each line that has code
1294 generated for it. The effect is that every entry in the
1295 matrix recommends the beginning of each represented line as
1296 a breakpoint location. This is the traditional practice for
1299 \textit{A more sophisticated approach might involve multiple entries in
1300 the matrix for a line number; in this case, at least one entry
1301 (often but not necessarily only one) specifies a recommended
1302 breakpoint location for the line number. \DWLNSnegatestmt{}
1303 opcodes in the line number program control which matrix entries
1304 constitute such a recommendation and
1305 \addttindex{default\_is\_stmt} might
1306 be either \doublequote{true} or \doublequote{false.} This approach might be
1307 used as part of support for debugging optimized code.}
1309 \item \texttt{line\_base} (\HFTsbyte) \\
1310 \addttindexx{line\_base}
1311 This parameter affects the meaning of the special opcodes. See below.
1313 \item \texttt{line\_range} (\HFTubyte) \\
1314 \addttindexx{line\_range}
1315 This parameter affects the meaning of the special opcodes. See below.
1318 \item \texttt{opcode\_base} (\HFTubyte) \\
1320 \addttindexx{opcode\_base}
1321 number assigned to the first special opcode.
1323 \textit{Opcode base is typically one greater than the highest-numbered
1324 \addttindexx{opcode\_base}
1325 standard opcode defined for the specified version of the line
1326 number information (12 in DWARF Versions 3, 4 and 5,
1327 \addtoindexx{DWARF Version 3}
1328 \addtoindexx{DWARF Version 4}
1329 \addtoindexx{DWARF Version 5}
1331 \addtoindexx{DWARF Version 2}
1333 If opcode\_base is less than the typical value,
1334 \addttindexx{opcode\_base}
1335 then standard opcode numbers greater than or equal to the
1336 opcode base are not used in the line number table of this unit
1337 (and the codes are treated as special opcodes). If \texttt{opcode\_base}
1338 is greater than the typical value, then the numbers between
1339 that of the highest standard opcode and the first special
1340 opcode (not inclusive) are used for vendor specific extensions.}
1343 \item \texttt{standard\_opcode\_lengths} (array of \HFTubyte) \\
1344 \addttindexx{standard\_opcode\_lengths}
1345 This array specifies the number of \addtoindex{LEB128} operands for each
1346 of the standard opcodes. The first element of the array
1347 corresponds to the opcode whose value is 1, and the last
1348 element corresponds to the opcode whose value
1349 is \texttt{opcode\_base - 1}.
1351 \textit{By increasing \texttt{opcode\_base}, and adding elements to this array,
1352 \addttindexx{opcode\_base}
1353 new standard opcodes can be added, while allowing consumers who
1354 do not know about these new opcodes to be able to skip them.}
1356 \textit{Codes for vendor specific extensions, if any, are described
1357 just like standard opcodes.}
1359 %%% Save the current enum counter so we can restart later
1360 %%% End this enumeration so the following text is outdented to
1361 %%% the left margin (because it applies to the many following
1363 \newcounter{saveenumi}
1364 \setcounter{saveenumi}{\value{enumi}}
1368 \textit{The remaining fields provide information about the
1369 source files used in the compilation. These fields
1370 have been revised in \DWARFVersionV{} to support these
1374 \textit{To allow new alternative means for a consumer to
1375 check that a file it can access is the same version
1376 as that used in the compilation.}
1378 \textit{To allow a producer to collect file name strings
1379 in a new section (\dotdebuglinestr{}) that can be used
1380 to merge duplicate file name strings.}
1382 \textit{To add the ability for producers to provide
1383 vendor-defined information that can be skipped by a consumer
1384 that is unprepared to process it.}
1387 \begin{enumerate}[1. ]
1388 %%% Resume enumeration count where it left off above
1389 \setcounter{enumi}{\value{saveenumi}}
1390 \item \texttt{directory\_entry\_format\_count} (\HFTubyte) \\
1391 \addttindexx{directory\_entry\_format\_count}
1392 A count of the number of entries that occur in the
1393 following \addttindex{directory\_entry\_format} field.
1396 \item \texttt{directory\_entry\_format} (sequence of ULEB128 pairs) \\
1397 \addttindexx{directory\_entry\_format}
1398 A sequence of directory entry format descriptions.
1399 Each description consists of a pair of ULEB128 values:
1401 \setlength{\itemsep}{0em}
1402 \item A content type code (see
1403 Sections \refersec{chap:standardcontentdescriptions} and
1404 \refersec{chap:vendordefinedcontentdescriptions}).
1406 \item A form code using the attribute form codes
1410 \item \texttt{directories\_count} (ULEB128) \\
1411 \addttindexx{directories\_count}
1412 A count of the number of entries that occur in the
1413 following directories field.
1416 \item \texttt{directories} (sequence of directory names) \\
1417 \addttindexx{directories}
1418 A sequence of directory names and optional related
1419 information. Each entry is encoded as described
1420 by the \addttindex{directory\_entry\_format} field.
1422 Entries in this sequence describe each path that was
1423 searched for included source files in this compilation,
1424 including the compilation directory of the compilation.
1425 (The paths include those directories specified by the
1426 user for the compiler to search and those the compiler
1427 searches without explicit direction.)
1429 The first entry is the current directory of the compilation.
1430 Each additional path entry is either a full path name or
1431 is relative to the current directory of the compilation.
1433 The line number program assigns a number (index) to each
1434 of the directory entries in order, beginning with 0.
1436 \textit{Prior to \DWARFVersionV, the current directory was not
1437 represented in the directories field and a directory index
1438 of 0 implicitly referred to that directory as found in the
1439 \DWATcompdir{} attribute of the compilation unit
1440 debugging information entry.
1441 In \DWARFVersionV, the current directory is explicitly present
1442 in the directories field. This is needed to support the
1443 common practice of stripping all but the line number sections
1444 (\dotdebugline{} and \dotdebuglinestr) from an executable.}
1446 \textit{Note that if a \dotdebuglinestr{} section is present,
1447 both the compilation unit debugging information entry
1448 and the line number header can
1449 share a single copy of the current directory name string.}
1451 \item \texttt{file\_name\_entry\_format\_count} (\HFTubyte) \\
1452 \addttindexx{file\_name\_entry\_format\_count}
1453 A count of the number of file entry format entries that
1454 occur in the following \addttindex{file\_name\_entry\_format} field.
1455 If this field is zero, then the \addttindex{file\_names\_count} field
1456 (see below) must also be zero.
1459 \item \texttt{file\_name\_entry\_format} (sequence of ULEB128 pairs) \\
1460 \addttindexx{file\_name\_entry\_format}
1461 A sequence of file entry format descriptions.
1462 Each description consists of a pair of ULEB128 values:
1464 \setlength{\itemsep}{0em}
1465 \item A content type code (see below)
1466 \item A form code using the attribute form codes
1469 \item \texttt{file\_names\_count} (ULEB128) \\
1470 \addttindexx{file\_names\_count}
1471 A count of the number of file name entries that occur
1472 in the following \addttindex{file\_names} field.
1475 \item \texttt{file\_names} (sequence of file name entries) \\
1476 \addttindexx{file\_names}
1477 A sequence of file names and optional related
1478 information. Each entry is encoded as described
1479 by the \addttindex{file\_name\_entry\_format} field.
1481 Entries in this sequence describe source files that
1482 contribute to the line number information for this
1483 compilation or is used in other contexts, such as in
1484 a declaration coordinate or a macro file inclusion.
1486 The first entry in the sequence is the primary source file
1487 whose file name exactly matches that given in the
1488 \DWATname{} attribute in the compilation unit
1489 debugging information entry.
1491 The line number program references file names in this
1492 sequence beginning with 0, and uses those numbers instead
1493 of file names in the line number program that follows.
1495 \textit{Prior to \DWARFVersionV, the current compilation
1496 file name was not represented in the \addttindex{file\_names}
1497 field. In \DWARFVersionV, the current compilation file name
1498 is explicitly present and has index 0. This is needed to support
1499 the common practice of stripping all but the line number sections
1500 (\dotdebugline{} and \dotdebuglinestr) from an executable.}
1502 \textit{Note that if a \dotdebuglinestr{} section is present,
1503 both the compilation unit debugging information entry
1504 and the line number header can
1505 share a single copy of the current file name string.}
1510 \subsubsection{Standard Content Descriptions}
1511 \label{chap:standardcontentdescriptions}
1512 DWARF-defined content type codes are used to indicate
1513 the type of information that is represented in one
1514 component of an include directory or file name description.
1515 The following type codes are defined.
1516 \begin{enumerate}[1. ]
1518 \item \DWLNCTpathTARG \\
1519 The component is a null-terminated path name string.
1520 If the associated form code is \DWFORMstring{}, then the
1521 string occurs immediately in the containing \texttt{directories}
1522 or \addttindex{file\_names} field. If the form code is \DWFORMlinestrp{},
1523 then the string is included in the \dotdebuglinestr{} section
1524 and its offset occurs immediately in the containing
1525 \addttindex{directories} or \addttindex{file\_names} field.
1527 In the 32-bit DWARF format, the representation of a
1528 \DWFORMlinestrp{} value is a 4-byte unsigned offset; in the
1529 64-bit DWARF format, it is an 8-byte unsigned offset (see
1530 Section \refersec{datarep:32bitand64bitdwarfformats}).
1532 \textit{Note that this use of \DWFORMlinestrp{} is similar to
1533 \DWFORMstrp{} but refers to the \dotdebuglinestr{} section,
1536 In a \dotdebuglinedwo{} section, the form \DWFORMstrx{} may
1537 also be used. This refers into the \dotdebugstroffsetsdwo{}
1538 section (and indirectly also the \dotdebugstrdwo{} section)
1539 because no \texttt{.debug\_line\_str\_offsets.dwo} or
1540 \texttt{.debug\_line\_str.dwo} sections exist or are defined for
1541 use in split objects. (The form \DWFORMstring{} may also be used,
1542 but this precludes the benefits of string sharing.)
1544 \item \DWLNCTdirectoryindexTARG \\
1545 The unsigned directory index represents an entry in the
1546 directories field of the header. The index is 0 if
1547 the file was found in the current directory of the compilation
1548 (hence, the first directory in the directories field),
1549 1 if it was found in the second directory in the directories
1552 This content code is always paired with one of \DWFORMdataone,
1553 \DWFORMdatatwo{} or \DWFORMudata.
1555 \textit{The optimal form for a producer to use (which results in the
1556 minimum size for the set of \addttindex{include\_index} fields) depends not only
1557 on the number of directories in the directories
1558 field, but potentially on the order in which those directories are
1559 listed and the number of times each is used in the \addttindex{file\_names} field.}
1562 \item \DWLNCTtimestampTARG \\
1563 \DWLNCTtimestampNAME{} indicates that the value is the implementation-defined
1564 time of last modification of the file, or 0 if not available.
1565 It is always paired with one of the forms
1566 \DWFORMudata, \DWFORMdatafour, \DWFORMdataeight{} or \DWFORMblock.
1568 \item \DWLNCTsizeTARG \\
1569 \DWLNCTsizeNAME{} indicates that the value is the unsigned size of the
1570 file in bytes, or 0 if not available. It is paired with one of the
1571 forms \DWFORMudata, \DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour{}
1572 or \DWFORMdataeight.
1574 \item \DWLNCTMDfiveTARG \\
1575 \DWLNCTMDfiveNAME{} indicates that the value is a 16-byte \MDfive{} digest
1576 of the file contents. It is paired with form \DWFORMdatasixteen.
1579 \textit{An example that uses this line number header format
1580 is found in Appendix \refersec{app:linenumberheaderexample}.}
1582 \subsubsection{Vendor-defined Content Descriptions}
1583 \label{chap:vendordefinedcontentdescriptions}
1584 Vendor-defined content descriptions may be defined using content
1585 type codes in the range \DWLNCTlouserNAME{} to \DWLNCThiuserNAME{}. Each
1586 such code may be combined with one or more forms from the set:
1587 \DWFORMblock, \DWFORMblockone, \DWFORMblocktwo, \DWFORMblockfour,
1588 \DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour, \DWFORMdataeight,
1590 \DWFORMflag, \DWFORMlinestrp, \DWFORMsdata, \DWFORMsecoffset,
1591 \DWFORMstring, \DWFORMstrp, \DWFORMstrx{} and \DWFORMudata.
1593 If a consumer encounters a vendor-defined content type that
1594 it does not understand, it should skip the content data as though
1595 it were not present.
1598 \subsection{The Line Number Program}
1599 \label{chap:linenumberprogram}
1600 As stated before, the goal of a line number program is to build
1601 a matrix representing one compilation unit, which may have
1602 produced multiple sequences of target machine instructions.
1603 Within a sequence, addresses and
1604 \addtoindex{operation pointer}s may only increase.
1605 (Line numbers may decrease in cases of pipeline
1606 scheduling or other optimization.)
1609 \subsubsection{Special Opcodes}
1610 \label{chap:specialopcodes}
1611 Each \HFTubyte{} special opcode has the following effect on the state machine:
1613 \begin{enumerate}[1. ]
1615 \item Add a signed integer to the \texttt{line} register.
1617 \item Modify the \addtoindex{operation pointer} by incrementing the
1618 \texttt{address} and \addttindex{op\_index} registers as described below.
1620 \item Append a row to the matrix using the current values
1621 of the state machine registers.
1623 \item Set the \addttindex{basic\_block} register to \doublequote{false.} \addtoindexx{basic block}
1624 \item Set the \addttindex{prologue\_end} register to \doublequote{false.}
1625 \item Set the \addttindex{epilogue\_begin} register to \doublequote{false.}
1626 \item Set the \addttindex{discriminator} register to 0.
1630 All of the special opcodes do those same seven things; they
1631 differ from one another only in what values they add to the
1632 \texttt{line}, \texttt{address} and \addttindex{op\_index} registers.
1635 \textit{Instead of assigning a fixed meaning to each special opcode,
1636 the line number program uses several parameters in the header
1637 to configure the instruction set. There are two reasons
1638 for this. First, although the opcode space available for
1639 special opcodes ranges from 13 through 255, the lower
1640 bound may increase if one adds new standard opcodes. Thus, the
1641 \texttt{opcode\_base} field of the line number program header gives the
1642 value of the first special opcode. Second, the best choice of
1643 special\dash opcode meanings depends on the target architecture. For
1644 example, for a RISC machine where the compiler\dash generated code
1645 interleaves instructions from different lines to schedule
1646 the pipeline, it is important to be able to add a negative
1647 value to the \texttt{line} register to express the fact that a later
1648 instruction may have been emitted for an earlier source
1649 line. For a machine where pipeline scheduling never occurs,
1650 it is advantageous to trade away the ability to decrease
1651 the \texttt{line} register (a standard opcode provides an alternate
1652 way to decrease the line number) in return for the ability
1653 to add larger positive values to the \texttt{address} register. To
1654 permit this variety of strategies, the line number program
1656 \addttindex{line\_base}
1657 field that specifies the minimum
1658 value which a special opcode can add to the line register
1660 \addttindex{line\_range}
1661 field that defines the range of values it
1662 can add to the line register.}
1665 A special opcode value is chosen based on the amount that needs
1666 to be added to the \texttt{line}, \texttt{address} and \addttindex{op\_index} registers.
1667 The maximum line increment for a special opcode is the value
1669 \addttindex{line\_base}
1670 field in the header, plus the value of the
1671 \addttindex{line\_range} field, minus 1 (line base +
1673 If the desired line increment is greater than the maximum
1674 line increment, a standard opcode must be used instead of a
1675 special opcode. The \addtoindex{operation advance} represents the number
1676 of operations to skip when advancing the \addtoindex{operation pointer}.
1679 The special opcode is then calculated using the following formula:
1682 (\textit{desired line increment} - \addttindex{line\_base}) +
1683 (\addttindex{line\_range} * \textit{operation advance}) + \addttindex{opcode\_base}
1685 If the resulting opcode is greater than 255, a standard opcode
1686 must be used instead.
1688 \textit{When \addttindex{maximum\_operations\_per\_instruction} is 1,
1689 the operation advance is simply the address increment divided by the
1690 \addttindex{minimum\_instruction\_length}.}
1693 To decode a special opcode, subtract the \addttindex{opcode\_base} from
1694 the opcode itself to give the \textit{adjusted opcode}.
1695 The \textit{operation advance}
1696 is the result of the adjusted opcode divided by the
1697 \addttindex{line\_range}. The new \texttt{address} and
1698 \addttindex{op\_index} values are given by
1700 \textit{adjusted opcode} = opcode \dash opcode\_base
1701 \textit{operation advance} = \textit{adjusted opcode} / line\_range
1703 new address = address +
1704 \addttindex{minimum\_instruction\_length} *
1705 ((\addttindex{op\_index} + \addtoindex{operation advance}) / \addttindex{maximum\_operations\_per\_instruction})
1708 (\addttindex{op\_index} + \addtoindex{operation advance}) \% \addttindex{maximum\_operations\_per\_instruction}
1711 \textit{When the \addttindex{maximum\_operations\_per\_instruction}
1713 \texttt{op\_index} is always 0 and these calculations simplify to
1714 those given for addresses in \DWARFVersionIII{} and earlier.}
1716 The amount to increment the line register is the
1717 \addttindex{line\_base} plus
1719 \textit{\addtoindex{adjusted opcode}} modulo the
1720 \addttindex{line\_range}. That
1724 line increment = \addttindex{line\_base} + (\textit{adjusted opcode} \% \addttindex{line\_range})
1727 \textit{See Appendix \refersec{app:linenumberspecialopcodeexample} for an example.}
1731 \subsubsection{Standard Opcodes}
1732 \label{chap:standardopcodes}
1734 The standard opcodes, their applicable operands and the
1735 actions performed by these opcodes are as follows:
1737 \begin{enumerate}[1. ]
1739 \item \textbf{\DWLNScopyTARG} \\
1740 The \DWLNScopyNAME{}
1741 opcode takes no operands. It appends a row
1742 to the matrix using the current values of the state machine
1743 registers. Then it sets the \addttindex{discriminator} register to 0,
1744 and sets the \addttindex{basic\_block},
1745 \addttindex{prologue\_end} and
1746 \addttindex{epilogue\_begin}
1747 registers to \doublequote{false.}
1750 \item \textbf{\DWLNSadvancepcTARG} \\
1751 The \DWLNSadvancepcNAME{}
1752 opcode takes a single unsigned LEB128\addtoindexx{LEB128!unsigned}
1753 operand as the \addtoindex{operation advance} and modifies the \texttt{address}
1754 and \addttindex{op\_index} registers as specified in
1755 Section \refersec{chap:specialopcodes}.
1757 \item \textbf{\DWLNSadvancelineTARG} \\
1758 The \DWLNSadvancelineNAME{}
1759 opcode takes a single signed LEB128\addtoindexx{LEB128!signed}
1760 operand and adds that value to the \texttt{line} register of the
1764 \item \textbf{\DWLNSsetfileTARG} \\
1765 The \DWLNSsetfileNAME{} opcode takes a single
1766 unsigned LEB128\addtoindexx{LEB128!unsigned}
1767 operand and stores it in the \texttt{file} register
1768 of the state machine.
1771 \item \textbf{\DWLNSsetcolumnTARG} \\
1772 The \DWLNSsetcolumnNAME{} opcode takes a
1773 single unsigned LEB128\addtoindexx{LEB128!unsigned} operand
1774 and stores it in the \texttt{column}
1775 register of the state machine.
1778 \item \textbf{\DWLNSnegatestmtTARG} \\
1779 The \DWLNSnegatestmtNAME{} opcode takes no
1780 operands. It sets the \addttindex{is\_stmt} register of the state machine
1781 to the logical negation of its current value.
1784 \item \textbf{\DWLNSsetbasicblockTARG} \\
1785 The \DWLNSsetbasicblockNAME{}
1787 \addtoindexx{basic block}
1789 It sets the \addttindex{basic\_block} register of the
1790 state machine to \doublequote{true.}
1792 \item \textbf{\DWLNSconstaddpcTARG} \\
1793 The \DWLNSconstaddpcNAME{} opcode takes
1794 no operands. It advances the \texttt{address} and \addttindex{op\_index} registers
1795 by the increments corresponding to special opcode 255.
1797 \textit{When the line number program needs to advance the \texttt{address}
1798 by a small amount, it can use a single special opcode,
1799 which occupies a single byte. When it needs to advance the
1800 \texttt{address} by up to twice the range of the last special opcode,
1801 it can use \DWLNSconstaddpc{} followed by a special opcode,
1802 for a total of two bytes. Only if it needs to advance the
1803 address by more than twice that range will it need to use
1804 both \DWLNSadvancepc{} and a special opcode, requiring three
1807 \item \textbf{\DWLNSfixedadvancepcTARG} \\
1808 The \DWLNSfixedadvancepcNAME{} opcode
1809 takes a single \HFTuhalf{} (unencoded) operand and adds it to the
1810 \texttt{address} register of the state machine and sets the \addttindex{op\_index}
1811 register to 0. This is the only standard opcode whose operand
1812 is \textbf{not} a variable length number. It also does
1813 \textbf{not} multiply the
1814 operand by the \addttindex{minimum\_instruction\_length}
1815 field of the header.
1817 \textit{Some assemblers may not be able emit
1818 \DWLNSadvancepc{} or special opcodes because they cannot encode
1819 \addtoindex{LEB128} numbers or judge when
1820 the computation of a special opcode overflows and requires
1821 the use of \DWLNSadvancepc. Such assemblers, however, can
1822 use \DWLNSfixedadvancepc{} instead, sacrificing compression.}
1825 \item \textbf{\DWLNSsetprologueendTARG} \\
1826 The \DWLNSsetprologueendNAME{}
1827 opcode takes no operands. It sets the
1828 \addttindex{prologue\_end} register
1829 to \doublequote{true.}
1831 \textit{When a breakpoint is set on entry to a function, it is
1832 generally desirable for execution to be suspended, not on the
1833 very first instruction of the function, but rather at a point
1834 after the function's frame has been set up, after any language
1835 defined local declaration processing has been completed,
1836 and before execution of the first statement of the function
1837 begins. Debuggers generally cannot properly determine where
1838 this point is. This command allows a compiler to communicate
1839 the location(s) to use.}
1841 \textit{In the case of optimized code, there may be more than one such
1842 location; for example, the code might test for a special case
1843 and make a fast exit prior to setting up the frame.}
1845 \textit{Note that the function to which the
1846 \addtoindex{prologue end} applies cannot
1847 be directly determined from the line number information alone;
1848 it must be determined in combination with the subroutine
1849 information entries of the compilation (including inlined
1853 \item \textbf{\DWLNSsetepiloguebeginTARG} \\
1854 The \DWLNSsetepiloguebeginNAME{} opcode takes no operands. It
1855 sets the \addttindex{epilogue\_begin} register to \doublequote{true.}
1857 \textit{When a breakpoint is set on the exit of a function or execution
1858 steps over the last executable statement of a function, it is
1859 generally desirable to suspend execution after completion of
1860 the last statement but prior to tearing down the frame (so that
1861 local variables can still be examined). Debuggers generally
1862 cannot properly determine where this point is. This command
1863 allows a compiler to communicate the location(s) to use.}
1865 \textit{Note that the function to which the
1866 \addtoindex{epilogue end} applies cannot
1867 be directly determined from the line number information alone;
1868 it must be determined in combination with the subroutine
1869 information entries of the compilation (including inlined
1872 \textit{In the case of a trivial function, both
1873 \addtoindex{prologue end} and
1874 \addtoindex{epilogue begin} may occur at the same address.}
1876 \item \textbf{\DWLNSsetisaTARG} \\
1877 The \DWLNSsetisaNAME{} opcode takes a single
1878 unsigned LEB128\addtoindexx{LEB128!unsigned} operand and stores that value in the
1880 register of the state machine.
1884 \subsubsection{Extended Opcodes}
1885 \label{chap:extendedopcodes}
1887 The extended opcodes are as follows:
1889 \begin{enumerate}[1. ]
1891 \item \textbf{\DWLNEendsequenceTARG} \\
1892 The \DWLNEendsequenceNAME{} opcode takes no operands. It sets the
1893 \addttindex{end\_sequence}
1894 register of the state machine to \doublequote{true} and
1895 appends a row to the matrix using the current values of the
1896 state-machine registers. Then it resets the registers to the
1897 initial values specified above
1898 (see Section \refersec{chap:statemachineregisters}).
1900 number program sequence must end with a \DWLNEendsequence{}
1901 instruction which creates a row whose address is that of the
1902 byte after the last target machine instruction of the sequence.
1905 \item \textbf{\DWLNEsetaddressTARG} \\
1906 The \DWLNEsetaddressNAME{} opcode takes a single relocatable
1907 address as an operand. The size of the operand is the size
1908 of an address on the target machine. It sets the \texttt{address}
1909 register to the value given by the relocatable address and
1910 sets the \addttindex{op\_index} register to 0.
1912 \textit{All of the other line number program opcodes that
1913 affect the \texttt{address} register add a delta to it. This instruction
1914 stores a relocatable value into it instead.}
1916 \item \textbf{\DWLNEsetdiscriminatorTARG} \\
1917 The \DWLNEsetdiscriminatorNAME{}
1918 opcode takes a single
1919 parameter, an unsigned LEB128\addtoindexx{LEB128!unsigned}
1920 integer. It sets the
1921 \addttindex{discriminator} register to the new value.
1925 \textit{The DW\_LNE\_define\_file operation defined
1926 in earlier versions of DWARF is deprecated in \DWARFVersionV.}
1927 \addtoindexx{DW\_LNE\_define\_file (deprecated)}
1929 \textit{Appendix \refersec{app:linenumberprogramexample}
1930 gives some sample line number programs.}
1932 \section{Macro Information}
1933 \label{chap:macroinformation}
1934 \textit{Some languages, such as
1936 \addtoindex{C++}, provide a way to replace
1937 \addtoindexx{macro information}
1938 text in the source program with macros defined either in the
1939 source file itself, or in another file included by the source
1940 file. Because these macros are not themselves defined in the
1941 target language, it is difficult to represent their definitions
1942 using the standard language constructs of DWARF. The debugging
1943 information therefore reflects the state of the source after
1944 the macro definition has been expanded, rather than as the
1945 programmer wrote it. The macro information table provides a way
1946 of preserving the original source in the debugging information.}
1949 Section \refersec{chap:fullandpartialcompilationunitentries},
1950 the macro information for a
1951 given compilation unit is represented in the
1953 section of an object file.
1956 \textit{The \dotdebugmacro{} section is new in
1957 \DWARFVersionV, and supersedes the
1958 \dotdebugmacinfo{} section of earlier DWARF versions.
1959 While \dotdebugmacro{} and \dotdebugmacinfo{}
1960 sections cannot both occur in the same compilation unit, both may be found in the
1961 set of units that make up an executable or shared object file.}
1963 \textit{The representation of debugging information in the \dotdebugmacinfo{} section is specified
1964 in earlier versions of the DWARF standard. Note that the \dotdebugmacinfo{} section does not contain
1965 any headers and does not support sharing of strings or sharing of repeated macro sequences.}
1967 The macro information for each compilation unit consists of one or
1968 more macro units. Each macro unit starts with a header
1969 and is followed by a series of macro information entries or file
1970 inclusion entries. Each entry consists of an opcode followed by
1971 zero or more operands. Each macro unit ends with an entry
1972 containing an opcode of 0.
1974 In all macro information entries,
1975 the line number of the entry is encoded as an
1976 unsigned LEB128 integer.
1979 \subsection{Macro Information Header}
1980 The macro information header contains the following fields:
1982 \begin{enumerate}[1. ]
1983 \item \texttt{version} (\HFTuhalf) \\
1984 A version number (see Section \refersec{datarep:macroinformation}).
1985 This number is specific to the macro information and is independent
1986 of the DWARF version number.
1988 \item \texttt{flags} (\HFTubyte) \\
1989 The bits of the \texttt{flags} field are interpreted as a set
1990 of flags, some of which may indicate that additional fields follow.
1993 The following flags, beginning with the least significant bit, are defined:
1995 \item \HFNoffsetsizeflag \\
1996 If the \HFNoffsetsizeflag{} is zero, the header is for a 32-bit
1997 DWARF format macro section and all offsets are 4 bytes long;
1998 if it is one, the header is for a 64-bit DWARF format macro section
1999 and all offsets are 8 bytes long.
2001 \item \addttindex{debug\_line\_offset\_flag} \\
2002 If the \addttindex{debug\_line\_offset\_flag} is one,
2003 the \addttindex{debug\_line\_offset} field (see below) is present.
2004 If zero, that field is omitted.
2006 \item \addttindex{opcode\_operands\_table\_flag} \\
2007 If the \addttindex{opcode\_operands\_table\_flag} is one,
2008 the \addttindex{opcode\_operands\_table} field (see below) is present.
2009 If zero, that field is omitted.
2012 All other flags are reserved by DWARF.
2014 \item \addttindex{debug\_line\_offset} \\
2015 An offset in the \dotdebugline{} section of the
2016 beginning of the line number information in the containing
2017 compilation, encoded as a 4-byte offset for a 32-bit DWARF
2018 format macro section and an 8-byte offset for a 64-bit DWARF format
2021 \item \addttindex{opcode\_operands\_table} \\
2022 An \texttt{opcode\_operands\_table} describing the operands
2023 of the macro information entry opcodes.
2025 The macro information entries defined in this standard may, but need not, be
2026 described in the table, while other user-defined entry opcodes used in the section
2027 are described there. Vendor extension entry opcodes are
2028 allocated in the range from \DWMACROlouser{} to \DWMACROhiuser. Other
2029 unassigned codes are reserved for future DWARF standards.
2032 The table starts with a 1-byte \texttt{count} of the defined opcodes, followed by
2033 an entry for each of those opcodes. Each entry starts with a 1-byte unsigned
2034 opcode number, followed by unsigned LEB128\addtoindexx{ULEB128} encoded number of operands
2035 and for each operand there is a single unsigned byte describing the form in which
2036 the operand is encoded. The allowed forms are:
2037 \DWFORMblock, \DWFORMblockone, \DWFORMblocktwo, \DWFORMblockfour,
2038 \DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour, \DWFORMdataeight,
2039 \DWFORMdatasixteen, \DWFORMsdata, \DWFORMudata, \DWFORMflag, \DWFORMsecoffset,
2040 \DWFORMstring, \DWFORMstrp{} and \DWFORMstrx.
2043 \subsection{Macro Information Entries}
2044 \label{chap:macroinformationentries}
2045 All macro information entries within a \dotdebugmacro{}
2046 section for a given compilation unit appear in the same
2047 order in which the directives were processed by the
2048 compiler (after taking into account the effect of the
2049 macro import directives).
2051 \textit{The source file in which a macro information entry occurs
2052 can be derived by interpreting the sequence of entries from the
2053 beginning of the \dotdebugmacro{} section. \DWMACROstartfile{} and
2054 \DWMACROendfile{} indicate changes in the containing file.}
2056 \subsubsection{Define and Undefine Entries}
2057 \label{chap:defineandundefineentries}
2058 The define and undefine macro entries have multiple forms that
2059 use different representations of their two operands.
2061 While described in pairs below, the forms of define
2062 and undefine entries may be freely intermixed.
2064 \begin{enumerate}[1. ]
2066 \itembfnl{\DWMACROdefineTARG{}, \DWMACROundefTARG{}}
2067 A \DWMACROdefineNAME{} or \DWMACROundefNAME{} entry has two
2068 operands. The first operand encodes the source line number
2069 of the \texttt{\#define} or \texttt{\#undef} macro directive.
2070 The second operand is a null-terminated character
2071 string for the macro being defined or undefined.
2073 The contents of the operands are described below (see Sections
2074 \ref{chap:macrodefinestring} and \referfol{chap:macroundefinestring}).
2076 \itembfnl{\DWMACROdefinestrpTARG{}, \DWMACROundefstrpTARG{}}
2077 A \DWMACROdefinestrpNAME{} or \DWMACROundefstrpNAME{}
2078 entry has two operands. The first operand encodes the source line number
2079 of the \texttt{\#define} or \texttt{\#undef} macro directive.
2080 The second operand consists of an offset into a string table contained in
2081 the \dotdebugstr{} section of the object file. The size of the operand is
2082 given in the header \HFNoffsetsizeflag{} field.
2084 The contents of the operands are described below (see Sections
2085 \ref{chap:macrodefinestring} and \referfol{chap:macroundefinestring}).
2087 \itembfnl{\DWMACROdefinestrxTARG{}, \DWMACROundefstrxTARG{}}
2088 A \DWMACROdefinestrxNAME{} or \DWMACROundefstrxNAME{} entry
2089 has two operands. The first operand encodes the line number
2090 of the \texttt{\#define} or \texttt{\#undef} macro directive.
2091 The second operand identifies a string; it is represented using an
2092 unsigned LEB128\addtoindexx{ULEB128} encoded value,
2093 which is interpreted as a zero-based index into an array of offsets in the
2094 \dotdebugstroffsets{} section.
2096 The contents of the operands are described below (see Sections
2097 \ref{chap:macrodefinestring} and \referfol{chap:macroundefinestring}).
2100 \itembfnl{\DWMACROdefinesupTARG{}, \DWMACROundefsupTARG{}}
2101 A \DWMACROdefinesupNAME{} or \DWMACROundefsupNAME{} entry
2102 has two operands. The first operand encodes the line number
2103 of the \texttt{\#define} or \texttt{\#undef} macro directive.
2104 The second operand identifies a string; it is represented as
2105 an offset into a string table contained in the \dotdebugstr{}
2106 section of the \addtoindex{supplementary object file}.
2107 The size of the operand depends on the macro section header
2108 \HFNoffsetsizeflag{} field.
2110 The contents of the operands are described below (see Sections
2111 \ref{chap:macrodefinestring} and \referfol{chap:macroundefinestring}).
2116 \subsubsection{Macro Define String}
2117 \label{chap:macrodefinestring}
2120 \DWMACROdefinestrp{},
2121 \DWMACROdefinestrx{} or
2123 entry, the value of the
2124 second operand is the name of the macro symbol that is defined
2125 at the indicated source line, followed immediately by the
2126 \addtoindex{macro formal parameter list}
2127 including the surrounding parentheses (in
2128 the case of a function-like macro) followed by the definition
2129 string for the macro. If there is no formal parameter list,
2130 then the name of the defined macro is followed immediately by
2131 its definition string.
2133 In the case of a function-like macro definition, no whitespace
2134 characters appear between the name of the defined
2135 macro and the following left parenthesis. Formal parameters
2136 are separated by a comma without any whitespace.
2138 character separates the right parenthesis that terminates
2139 the formal parameter list and the following definition string.
2141 In the case of a \doublequote{normal} (that is, non-function-like) macro
2142 definition, exactly one space character separates the
2143 name of the defined macro from the following definition text.
2145 \subsubsection{Macro Undefine String}
2146 \label{chap:macroundefinestring}
2149 \DWMACROundefstrp{},
2150 \DWMACROundefstrx{} or
2152 entry, the value of the second string is the name of the pre-processor
2153 symbol that is undefined at the indicated source line.
2155 \subsubsection{Entries for Command Line Options}
2156 \label{chap:entriesforcommandlineoptions}
2157 \DWMACROdefineINDX{}\DWMACROdefinestrpINDX{}\DWMACROdefinestrxINDX
2158 \DWMACROundefINDX{}\DWMACROundefstrpINDX{}\DWMACROundefstrxINDX
2160 generates a define or undefine entry for
2161 each pre-processor symbol which is defined or undefined by
2162 some means other than such a directive
2163 within the compiled source text. In particular, pre-processor
2164 symbol definitions and undefinitions which occur as a
2165 result of command line options (when invoking the compiler)
2166 are represented by their own define and
2169 All such define and undefine entries representing compilation
2170 options appear before the first \DWMACROstartfile{}
2171 entry for that compilation unit
2172 (see Section \referfol{chap:fileinclusionentries})
2173 and encode the value 0 in their line number operands.
2175 \subsection{File Inclusion Entries}
2176 \label{chap:fileinclusionentries}
2178 \subsubsection{Source Include Directives}
2179 \label{chap:sourceincludedirectives}
2181 The following directives describe a source
2182 file inclusion directive (\texttt{\#include} in
2183 \addtoindex{C}/\addtoindex{C++}) and the
2184 ending of an included file.
2186 \begin{enumerate}[1. ]
2188 \itembfnl{\DWMACROstartfileTARG{}}
2189 A \DWMACROstartfileNAME{} entry has two operands. The
2190 first operand encodes the line number of the source line on
2191 which the \texttt{\#include} macro directive occurs.
2192 The second operand encodes a source file name index.
2194 The source file name index is the file number in the
2195 line number information table for the compilation unit.
2197 If a \DWMACROstartfileNAME{} entry is present, the header
2198 contains a reference to the \dotdebugline{} section of
2201 \itembfnl{\DWMACROendfileTARG{}}
2202 A \DWMACROendfileNAME{} entry has no operands. The presence of
2203 the entry marks the end of the current source file inclusion.
2208 When providing macro information in an object file,
2209 a producer generates \DWMACROstartfile{} and
2210 \DWMACROendfile{} entries for the source file submitted to
2211 the compiler for compilation. This \DWMACROstartfile{} entry
2212 has the value 0 in its line number operand and references
2213 the file entry in the line number information table for the
2214 primary source file.
2216 \subsubsection{Importation of Macro Units}
2217 \label{chap:importationofmacrounits}
2218 The import entries make it possible to replicate macro units.
2219 The first form supports replication within the current compilation
2220 and the second form supports replication across separate
2221 executable or shared object files.
2223 \textit{Import entries do not reflect the source program
2224 and, in fact, are not necessary at all. However, they do
2225 provide a mechanism that can be used to reduce redundancy
2226 in the macro information and thereby to save space.}
2228 \begin{enumerate}[1. ]
2230 \itembfnl{\DWMACROimportTARG{}}
2231 A \DWMACROimportNAME{} entry has one operand, an offset into
2232 another part of the \dotdebugmacro{} section that is
2233 the beginning of a target macro unit. The size of the operand
2234 depends on the header \HFNoffsetsizeflag{} field. The
2235 \DWMACROimportNAME{} entry instructs the consumer to
2236 replicate the sequence of entries following the target macro
2237 header which begins at the given
2238 \dotdebugmacro{} offset, up to, but excluding,
2239 the terminating entry with opcode \texttt{0},
2240 as though it occurs in place of the import operation.
2242 \itembfnl{\DWMACROimportsupTARG}
2243 A \DWMACROimportsupNAME{} entry has one operand, an
2244 offset from the start of the \dotdebugmacro{} section in the
2245 \addtoindex{supplementary object file}.
2246 The size of the operand depends on the section header
2247 \HFNoffsetsizeflag{} field.
2248 Apart from the different location in which to find the macro unit,
2249 this entry type is equivalent to \DWMACROimport.
2251 \textit{This entry type is aimed at sharing duplicate
2252 macro units between \dotdebugmacro{}
2253 sections from different executable or shared object files.}
2256 From within the \dotdebugmacro{} section of the
2257 \addtoindex{supplementary object file}, \DWMACROdefinestrp{}
2258 and \DWMACROundefstrp{} entries refer to the
2259 \dotdebugstr{} section of that same supplementary file;
2260 similarly, \DWMACROimport{} entries refer to the
2261 \dotdebugmacro{} section of that same supplementary file.
2267 \section{Call Frame Information}
2268 \label{chap:callframeinformation}
2269 \addtoindexx{unwind|see{virtual unwind}}\addtoindexx{virtual unwind}
2271 \textit{Debuggers often need to be able to view and modify the
2272 state of any subroutine activation that is
2273 \addtoindexx{activation of call frame}
2274 on the call stack. An activation consists of:}
2277 \item \textit{A code location that is within the
2278 subroutine. This location is either the place where the program
2279 stopped when the debugger got control (for example, a breakpoint), or
2280 is a place where a subroutine made a call or was interrupted
2281 by an asynchronous event (for example, a signal).}
2283 \item \textit{An area of memory that is allocated on a stack called a
2284 \doublequote{call frame.} The call frame is identified by an address
2285 on the stack. We refer to this address as the Canonical
2286 Frame Address or CFA. Typically, the CFA is defined to be the
2287 value of the stack pointer at the call site in the previous
2288 frame (which may be different from its value on entry to the
2291 \item \textit{A set of registers that are in use by the subroutine
2292 at the code location.}
2296 \textit{Typically, a set of registers are designated to be preserved
2297 across a call. If a callee wishes to use such a register, it
2298 saves the value that the register had at entry time in its call
2299 frame and restores it on exit. The code that allocates space
2300 on the call frame stack and performs the save operation is
2301 called the subroutine\textquoteright{s} \addtoindex{prologue}, and the code that performs
2302 the restore operation and deallocates the frame is called its
2303 \addtoindex{epilogue}. Typically, the
2304 \addtoindex{prologue} code is physically at the
2305 beginning of a subroutine and the
2306 \addtoindex{epilogue} code is at the end.}
2308 \textit{To be able to view or modify an activation that is not
2309 on the top of the call frame stack, the debugger must
2313 the stack of activations until
2314 it finds the activation of interest. A debugger
2319 a stack in steps. Starting with the current activation it
2320 virtually restores any registers that were preserved by the
2321 current activation and computes the predecessor\textquoteright{s} CFA and
2322 code location. This has the logical effect of returning from
2323 the current subroutine to its predecessor. We say that the
2324 debugger virtually unwinds the stack because the actual state
2325 of the target process is unchanged.}
2332 operation needs to know where registers are
2333 saved and how to compute the predecessor\textquoteright{s} CFA and code
2334 location. When considering an architecture-independent way
2335 of encoding this information one has to consider a number of
2338 \begin{itemize} % bullet list
2340 \item \textit{Prologue
2341 \addtoindexx{prologue}
2343 \addtoindex{epilogue} code is not always in
2344 distinct \nolink{blocks}
2345 at the beginning and end of a subroutine. It is common
2346 to duplicate the \addtoindex{epilogue} code
2347 at the site of each return
2348 from the code. Sometimes a compiler breaks up the register
2349 save/unsave operations and moves them into the body of the
2350 subroutine to just where they are needed.}
2353 \item \textit{Compilers use different ways to manage the call
2354 frame. Sometimes they use a frame pointer register, sometimes
2357 \item \textit{The algorithm to compute CFA changes as you progress through
2358 the \addtoindex{prologue}
2359 and \addtoindex{epilogue code}.
2360 (By definition, the CFA value
2363 \item \textit{Some subroutines have no call frame.}
2365 \item \textit{Sometimes a register is saved in another register that by
2366 convention does not need to be saved.}
2368 \item \textit{Some architectures have special instructions that perform
2369 some or all of the register management in one instruction,
2370 leaving special information on the stack that indicates how
2371 registers are saved.}
2373 \item \textit{Some architectures treat return address values specially. For
2374 example, in one architecture, the call instruction guarantees
2375 that the low order two bits will be zero and the return
2376 instruction ignores those bits. This leaves two bits of
2377 storage that are available to other uses that must be treated
2384 \subsection{Structure of Call Frame Information}
2385 \label{chap:structureofcallframeinformation}
2387 DWARF supports virtual unwinding by defining an architecture
2388 independent basis for recording how subprograms save and restore
2389 registers during their lifetimes. This basis must be augmented
2390 on some machines with specific information that is defined by
2391 an architecture specific ABI authoring committee, a hardware
2392 vendor, or a compiler producer. The body defining a specific
2393 augmentation is referred to below as the \doublequote{augmenter.}
2396 Abstractly, this mechanism describes a very large table that
2397 has the following structure:
2400 LOC CFA R0 R1 ... RN
2408 The first column indicates an address for every location
2409 that contains code in a program. (In shared object files, this
2410 is an object-relative offset.) The remaining columns contain
2411 virtual unwinding rules that are associated with the indicated
2414 The CFA column defines the rule which computes the Canonical
2415 Frame Address value; it may be either a register and a signed
2416 offset that are added together, or a DWARF expression that
2420 The remaining columns are labelled by register number. This
2421 includes some registers that have special designation on
2422 some architectures such as the PC and the stack pointer
2423 register. (The actual mapping of registers for a particular
2424 architecture is defined by the augmenter.) The register columns
2425 contain rules that describe whether a given register has been
2426 saved and the rule to find the value for the register in the
2430 The register rules are:
2432 \begin{longtable}{lP{9cm}}
2434 &A register that has this rule has no recoverable value in the previous frame.
2435 (By convention, it is not preserved by a callee.) \\
2438 &This register has not been modified from the previous frame. (By convention,
2439 it is preserved by the callee, but the callee has not modified it.) \\
2442 &The previous value of this register is saved at the address CFA+N where CFA
2443 is the current CFA value and N is a signed offset.\\
2446 &The previous value of this register is the value CFA+N where CFA is the
2447 current CFA value and N is a signed offset.\\
2450 &The previous value of this register is stored
2451 in another register numbered R.\\
2454 &The previous value of this register is located at the address produced by
2455 executing the DWARF expression E (see Section \refersec{chap:dwarfexpressions}).\\
2458 &The previous value of this register is the value produced by executing the
2459 DWARF expression E (see Section \refersec{chap:dwarfexpressions}).\\
2462 &The rule is defined externally to this specification by the augmenter.\\
2466 \textit{This table would be extremely large if actually constructed
2467 as described. Most of the entries at any point in the table
2468 are identical to the ones above them. The whole table can be
2469 represented quite compactly by recording just the differences
2470 starting at the beginning address of each subroutine in
2474 The virtual unwind information is encoded in a self-contained
2476 \dotdebugframe{}. Entries in a
2477 \dotdebugframe{} section
2478 are aligned on a multiple of the address size relative to
2479 the start of the section and come in two forms: a Common
2480 \addtoindexx{common information entry}
2481 Information Entry (CIE) and a
2482 \addtoindexx{frame description entry}
2483 Frame Description Entry (FDE).
2485 \textit{If the range of code addresses for a function is not
2486 contiguous, there may be multiple CIEs and FDEs corresponding
2487 to the parts of that function.}
2490 A Common Information Entry holds information that is shared
2491 among many Frame Description Entries. There is at least one
2492 CIE in every non-empty \dotdebugframe{} section. A CIE contains
2493 the following fields, in order:
2494 \begin{enumerate}[1. ]
2495 \item \HFNlength{} (\livelink{datarep:initiallengthvalues}{initial length}) \\
2496 A constant that gives the number of bytes of the CIE structure,
2497 not including the length field itself
2498 (see Section \refersec{datarep:initiallengthvalues}).
2500 size of the \texttt{length} field plus the value of \texttt{length} must be an
2501 integral multiple of the address size.
2503 \item \HFNCIEid{} (4 or 8 bytes, see Section \refersec{datarep:32bitand64bitdwarfformats}) \\
2504 A constant that is used to distinguish CIEs from FDEs.
2506 \item \HFNversion{} (\HFTubyte) \\
2507 A version number\addtoindexx{version number!call frame information}
2508 (see Section \refersec{datarep:callframeinformation}).
2509 This number is specific to the call frame information
2510 and is independent of the DWARF version number.
2513 \item \HFNaugmentation{} (\HFTaugstring) \\
2514 A null-terminated UTF\dash 8 string that identifies the augmentation
2515 to this CIE or to the FDEs that use it. If a reader encounters
2516 an augmentation string that is unexpected, then only the
2517 following fields can be read:
2522 \item CIE: \HFNlength, \HFNCIEid, \HFNversion, \HFNaugmentation
2524 \item FDE: \HFNlength, \HFNCIEpointer, \HFNinitiallocation, \HFNaddressrange
2527 If there is no augmentation, this value is a zero byte.
2530 \textit{The augmentation string allows users to indicate that there
2531 is additional target\dash specific information in the CIE or FDE
2536 unwind a stack frame. For example, this
2537 might be information about dynamically allocated data which
2538 needs to be freed on exit from the routine.}
2540 \textit{Because the \dotdebugframe{} section is useful independently of
2541 any \dotdebuginfo{} section, the augmentation string always uses
2542 UTF\dash 8 encoding.}
2545 \item \HFNaddresssize{} (\HFTubyte) \\
2546 The size of a target address in this CIE and any FDEs that
2547 use it, in bytes. If a compilation unit exists for this frame,
2548 its address size must match the address size here.
2550 \item \HFNsegmentselectorsize{} (\HFTubyte) \\
2551 The size of a segment selector in this CIE and any FDEs that
2554 \item \HFNcodealignmentfactor{} (unsigned LEB128)
2555 \addtoindexx{LEB128!unsigned}\addtoindexx{unsigned LEB128|see{LEB128, unsigned}}
2556 \addtoindexx{code alignment factor} \\
2558 \addtoindexx{\textless caf\textgreater|see{code alignment factor}}
2559 constant that is factored out of all advance location
2561 Section \refersec{chap:rowcreationinstructions}).
2562 The resulting value is
2563 \mbox{\textit{(operand} * \HFNcodealignmentfactor)}.
2565 \item \HFNdataalignmentfactor{} (signed LEB128)
2566 \addtoindexx{LEB128!signed}\addtoindexx{signed LEB128|see{LEB128, signed}} \\
2567 \addtoindexx{data alignment factor}
2569 \addtoindexx{\textless daf\textgreater|see{data alignment factor}}
2570 constant that is factored out of certain offset instructions
2571 (see Sections \refersec{chap:cfadefinitioninstructions} and
2572 \refersec{chap:registerruleinstructions}).
2573 The resulting value is \textit{(operand} *
2574 \HFNdataalignmentfactor).
2576 \item \HFNreturnaddressregister{} (unsigned LEB128)\addtoindexx{LEB128!unsigned} \\
2577 An unsigned LEB128 constant that indicates which column in the
2578 rule table represents the return address of the function. Note
2579 that this column might not correspond to an actual machine
2583 \item \HFNinitialinstructions{} (array of \HFTubyte) \\
2584 A sequence of rules that are interpreted to create the initial
2585 setting of each column in the table.
2587 The default rule for
2588 all columns before interpretation of the initial instructions
2589 is the undefined rule. However, an ABI authoring body or a
2590 compilation system authoring body may specify an alternate
2591 default value for any or all columns.
2593 \item \HFNpadding{} (array of \HFTubyte) \\
2594 Enough \DWCFAnop{} instructions to make the size of this entry
2595 match the length value above.
2599 An FDE contains the following fields, in order:
2600 \begin{enumerate}[1. ]
2601 \item \HFNlength{} (\livelink{datarep:initiallengthvalues}{initial length}) \\
2602 A constant that gives the number of bytes of the header and
2603 instruction stream for this function, not including the length
2605 (see Section \refersec{datarep:initiallengthvalues}).
2606 The size of the \texttt{length} field
2607 plus the value of length must be an integral multiple of the
2610 \item \HFNCIEpointer{} (4 or 8 bytes, see Section \refersec{datarep:32bitand64bitdwarfformats}) \\
2612 \addtoindexx{section offset!in FDE header}
2613 offset into the \dotdebugframe{}
2614 section that denotes
2615 the CIE that is associated with this FDE.
2618 \item \HFNinitiallocation{} (segment selector and target address) \\
2619 The address of the first location associated with this table
2621 If the \HFNsegmentselectorsize{} field of this FDE's CIE is non-zero,
2622 the initial location is preceded by a segment selector of
2626 \item \HFNaddressrange{} (target address) \\
2628 \addtoindexx{target address}
2629 of bytes of program instructions described by this entry.
2631 \item \HFNinstructions{} (array of \HFTubyte) \\
2632 A sequence of table defining instructions that are described
2633 in Section \refersec{chap:callframeinstructions}.
2636 \item \HFNpadding{} (array of \HFTubyte) \\
2637 Enough \DWCFAnop{} instructions
2638 to make the size of this entry match the \HFNlength{} value above.
2642 \subsection{Call Frame Instructions}
2643 \label{chap:callframeinstructions}
2645 Each call frame instruction is defined to take 0 or more
2646 operands. Some of the operands may be encoded as part of the
2648 (see Section \refersec{datarep:callframeinformation}).
2649 The instructions are defined in
2650 the following sections.
2653 Some call frame instructions have operands that are encoded
2654 as DWARF expressions
2655 (see Section \refersec{chap:generaloperations}).
2657 operators cannot be used in such operands:
2662 \DWOPaddrx, \DWOPcalltwo, \DWOPcallfour{}, \DWOPcallref,
2663 \DWOPconsttype, \DWOPconstx, \DWOPconvert, \DWOPdereftype,
2664 \DWOPregvaltype{} and \DWOPreinterpret{}
2666 not allowed in an operand of these instructions because
2667 the call frame information must not depend on other
2671 \item \DWOPpushobjectaddress{} is not meaningful in an operand
2672 of these instructions because there is no object context to
2673 provide a value to push.
2675 \item \DWOPcallframecfa{} is not meaningful in an operand of
2676 these instructions because its use would be circular.
2679 \textit{Call frame instructions to which these restrictions apply
2680 include \DWCFAdefcfaexpression, \DWCFAexpression{}
2681 and \DWCFAvalexpression.}
2684 \subsubsection{Row Creation Instructions}
2685 \label{chap:rowcreationinstructions}
2686 \begin{enumerate}[1. ]
2688 \item \textbf{\DWCFAsetlocTARG} \\
2689 The \DWCFAsetlocNAME{} instruction
2690 takes a single operand that
2691 represents a target address. The required action is to create a
2692 new table row using the specified address as the location. All
2693 other values in the new row are initially identical to the
2694 current row. The new location value is always greater than
2696 If the \HFNsegmentselectorsize{} field of this FDE's
2698 is non-zero, the initial location is preceded by a segment
2699 selector of the given length.
2702 \item \textbf{\DWCFAadvancelocTARG} \\
2703 The \DWCFAadvancelocNAME{} instruction takes a single operand (encoded
2704 with the opcode) that represents a constant delta. The required
2705 action is to create a new table row with a location value that
2706 is computed by taking the current entry\textquoteright s location value
2707 and adding the value of
2708 \textit{delta} * \addttindex{code\_alignment\_factor}.
2709 All other values in the new row are initially identical to the
2713 \item \textbf{\DWCFAadvanceloconeTARG{}} \\
2714 The \DWCFAadvanceloconeNAME{} instruction takes a single \HFTubyte{}
2715 operand that represents a constant delta. This instruction
2716 is identical to \DWCFAadvanceloc{} except for the encoding
2717 and size of the delta operand.
2719 \item \textbf{\DWCFAadvanceloctwoTARG} \\
2720 The \DWCFAadvanceloctwoNAME{} instruction takes a single \HFTuhalf{}
2721 operand that represents a constant delta. This instruction
2722 is identical to \DWCFAadvanceloc{} except for the encoding
2723 and size of the delta operand.
2725 \item \textbf{\DWCFAadvancelocfourTARG} \\
2726 The \DWCFAadvancelocfourNAME{} instruction takes a single \HFTuword{}
2727 operand that represents a constant delta. This instruction
2728 is identical to \DWCFAadvanceloc{} except for the encoding
2729 and size of the delta operand.
2733 \subsubsection{CFA Definition Instructions}
2734 \label{chap:cfadefinitioninstructions}
2735 \begin{enumerate}[1. ]
2737 \item \textbf{\DWCFAdefcfaTARG} \\
2738 The \DWCFAdefcfaNAME{}
2739 instruction takes two unsigned LEB128\addtoindexx{LEB128!unsigned}
2740 operands representing a register number and a (non-factored)
2741 offset. The required action is to define the current CFA rule
2742 to use the provided register and offset.
2745 \item \textbf{\DWCFAdefcfasfTARG} \\
2746 The \DWCFAdefcfasfNAME{} instruction takes two operands:
2747 an unsigned LEB128 value\addtoindexx{LEB128!unsigned}
2748 representing a register number and a
2749 signed LEB128\addtoindexx{LEB128!signed} factored offset. This instruction is identical
2750 to \DWCFAdefcfa{} except that the second operand is signed
2751 and factored. The resulting offset is \textit{factored\_offset} *
2752 \addttindex{data\_alignment\_factor}.
2755 \item \textbf{\DWCFAdefcfaregisterTARG} \\
2756 The \DWCFAdefcfaregisterNAME{}
2757 instruction takes a single
2758 unsigned LEB128\addtoindexx{LEB128!unsigned} operand representing a register number. The
2759 required action is to define the current CFA rule to use
2760 the provided register (but to keep the old offset). This
2761 operation is valid only if the current CFA rule is defined
2762 to use a register and offset.
2766 \item \textbf{\DWCFAdefcfaoffsetTARG} \\
2767 The \DWCFAdefcfaoffsetNAME{} instruction takes a single
2768 unsigned LEB128\addtoindexx{LEB128!unsigned} operand representing a (non-factored)
2769 offset. The required action is to define the current CFA rule
2770 to use the provided offset (but to keep the old register). This
2771 operation is valid only if the current CFA rule is defined
2772 to use a register and offset.
2775 \item \textbf{\DWCFAdefcfaoffsetsfTARG} \\
2776 The \DWCFAdefcfaoffsetsfNAME{} instruction takes a signed
2777 LEB128\addtoindexx{LEB128!signed} operand representing a factored offset. This instruction
2778 is identical to \DWCFAdefcfaoffset{} except that the
2779 operand is signed and factored. The resulting offset is
2780 \textit{factored\_offset} * \addttindex{data\_alignment\_factor}.
2782 is valid only if the current CFA rule is defined to use a
2783 register and offset.
2785 \item \textbf{\DWCFAdefcfaexpressionTARG} \\
2786 The \DWCFAdefcfaexpressionNAME{} instruction takes a
2787 \addtoindexx{exprloc class}
2788 single operand encoded as a
2789 \DWFORMexprloc{} value representing a
2790 DWARF expression. The required action is to establish that
2791 expression as the means by which the current CFA is computed.
2793 \textit{See Section \refersec{chap:callframeinstructions}
2794 regarding restrictions on the DWARF
2795 expression operators that can be used.}
2800 \subsubsection{Register Rule Instructions}
2801 \label{chap:registerruleinstructions}
2802 \begin{enumerate}[1. ]
2804 \item \textbf{\DWCFAundefinedTARG} \\
2805 The \DWCFAundefinedNAME{} instruction takes a single unsigned
2806 LEB128\addtoindexx{LEB128!unsigned} operand that represents a register number. The required
2807 action is to set the rule for the specified register to
2808 \doublequote{undefined.}
2810 \item \textbf{\DWCFAsamevalueTARG} \\
2811 The \DWCFAsamevalueNAME{} instruction takes a single unsigned
2812 LEB128 operand\addtoindexx{LEB128!unsigned} that represents a register number. The required
2813 action is to set the rule for the specified register to
2814 \doublequote{same value.}
2816 \item \textbf{\DWCFAoffsetTARG} \\
2817 The \DWCFAoffsetNAME{} instruction takes two operands: a register
2818 number (encoded with the opcode) and an unsigned LEB128\addtoindexx{LEB128!unsigned}
2819 constant representing a factored offset. The required action
2820 is to change the rule for the register indicated by the
2821 register number to be an offset(N) rule where the value of
2823 \textit{factored offset} * \addttindex{data\_alignment\_factor}.
2826 \item \textbf{\DWCFAoffsetextendedTARG} \\
2827 The \DWCFAoffsetextendedNAME{}
2828 instruction takes two unsigned LEB128\addtoindexx{LEB128!unsigned}
2829 operands representing a register number and a factored
2830 offset. This instruction is identical to
2832 except for the encoding and size of the register operand.
2835 \item \textbf{\DWCFAoffsetextendedsfTARG} \\
2836 The \DWCFAoffsetextendedsfNAME{}
2837 instruction takes two operands:
2838 an unsigned LEB128\addtoindexx{LEB128!unsigned}
2839 value representing a register number and a
2840 signed LEB128 factored offset. This instruction is identical
2841 to \DWCFAoffsetextended{}
2842 except that the second operand is
2843 signed and factored. The resulting offset is
2844 \textit{factored\_offset} * \addttindex{data\_alignment\_factor}.
2847 \item \textbf{\DWCFAvaloffsetTARG} \\
2848 The \DWCFAvaloffsetNAME{}
2849 instruction takes two unsigned
2850 LEB128 operands\addtoindexx{LEB128!unsigned} representing a register number and a
2851 factored offset. The required action is to change the rule
2852 for the register indicated by the register number to be a
2853 val\_offset(N) rule where the value of N is
2854 \textit{factored\_offset} * \addttindex{data\_alignment\_factor}.
2857 \item \textbf{\DWCFAvaloffsetsfTARG} \\
2858 The \DWCFAvaloffsetsfNAME{} instruction takes two operands: an
2859 unsigned LEB128\addtoindexx{LEB128!unsigned} value representing a register number and a
2860 signed LEB128\addtoindexx{LEB128!signed} factored offset. This instruction is identical
2861 to \DWCFAvaloffset{} except that the second operand is signed
2862 and factored. The resulting offset is
2863 \textit{factored\_offset} * \addttindex{data\_alignment\_factor}.
2865 \item \textbf{\DWCFAregisterTARG} \\
2866 The \DWCFAregisterNAME{}
2867 instruction takes two unsigned LEB128\addtoindexx{LEB128!unsigned}
2868 operands representing register numbers. The required action
2869 is to set the rule for the first register to be register(R)
2870 where R is the second register.
2872 \item \textbf{\DWCFAexpressionTARG} \\
2873 The \DWCFAexpressionNAME{} instruction takes two operands: an
2874 unsigned LEB128\addtoindexx{LEB128!unsigned}
2875 value representing a register number, and
2877 value representing a DWARF expression.
2879 required action is to change the rule for the register
2880 indicated by the register number to be an expression(E)
2881 rule where E is the DWARF expression. That is, the DWARF
2882 expression computes the address. The value of the CFA is
2883 pushed on the DWARF evaluation stack prior to execution of
2884 the DWARF expression.
2886 \textit{See Section \refersec{chap:callframeinstructions}
2887 regarding restrictions on the DWARF
2888 expression operators that can be used.}
2891 \item \textbf{\DWCFAvalexpressionTARG} \\
2892 The \DWCFAvalexpressionNAME{} instruction takes two operands:
2893 an unsigned LEB128\addtoindexx{LEB128!unsigned}
2894 value representing a register number, and
2896 value representing a DWARF expression. The
2897 required action is to change the rule for the register
2898 indicated by the register number to be a val\_expression(E)
2899 rule where E is the DWARF expression. That is, the DWARF
2900 expression computes the value of the given register. The value
2901 of the CFA is pushed on the DWARF evaluation stack prior to
2902 execution of the DWARF expression.
2904 \textit{See Section \refersec{chap:callframeinstructions}
2905 regarding restrictions on the DWARF
2906 expression operators that can be used.}
2909 \item \textbf{\DWCFArestoreTARG} \\
2910 The \DWCFArestoreNAME{} instruction takes a single operand (encoded
2911 with the opcode) that represents a register number. The
2912 required action is to change the rule for the indicated
2913 register to the rule assigned it by the \texttt{initial\_instructions}
2917 \item \textbf{\DWCFArestoreextendedTARG} \\
2918 The \DWCFArestoreextendedNAME{}
2919 instruction takes a single unsigned LEB128\addtoindexx{LEB128!unsigned}
2920 operand that represents a register number. This
2921 instruction is identical to \DWCFArestore{} except for the
2922 encoding and size of the register operand.
2926 \subsubsection{Row State Instructions}
2927 \label{chap:rowstateinstructions}
2929 \textit{The next two instructions provide the ability to stack and
2930 retrieve complete register states. They may be useful, for
2931 example, for a compiler that moves \addtoindex{epilogue} code
2933 body of a function.}
2936 \begin{enumerate}[1. ]
2938 \item \textbf{\DWCFArememberstateTARG} \\
2939 The \DWCFArememberstateNAME{} instruction takes no operands. The
2940 required action is to push the set of rules for every register
2941 onto an implicit stack.
2944 \item \textbf{\DWCFArestorestateTARG} \\
2945 The \DWCFArestorestateNAME{} instruction takes no operands. The
2946 required action is to pop the set of rules off the implicit
2947 stack and place them in the current row.
2951 \subsubsection{Padding Instruction}
2952 \label{chap:paddinginstruction}
2953 \begin{enumerate}[1. ]
2954 \item \textbf{\DWCFAnopTARG} \\
2955 The \DWCFAnopNAME{} instruction has no operands and no required
2956 actions. It is used as padding to make a CIE or FDE an
2961 \subsection{Call Frame Instruction Usage}
2962 \label{chap:callframeinstructionusage}
2964 \textit{To determine the virtual unwind rule set for a given location
2965 (L1), one searches through the FDE headers looking at the
2966 \addttindex{initial\_location} and \addttindex{address\_range} values to see if L1 is
2967 contained in the FDE. If so, then:}
2968 \begin{enumerate}[1. ]
2970 \item \textit{Initialize a register set by reading the
2971 \texttt{initial\_instructions} field of the associated CIE.}
2973 \item \textit{Read and process the FDE\textquoteright s instruction
2974 sequence until a \DWCFAadvanceloc,
2975 \DWCFAsetloc, or the
2976 end of the instruction stream is encountered.}
2978 \item \textit{ If a \DWCFAadvanceloc{} or \DWCFAsetloc{}
2979 instruction is encountered, then compute a new location value
2980 (L2). If L1 $\geq$ L2 then process the instruction and go back
2984 \item \textit{ The end of the instruction stream can be thought
2985 of as a \DWCFAsetloc{} (\addttindex{initial\_location} + \addttindex{address\_range})
2986 instruction. Note that the FDE is ill-formed if L2 is less
2991 \textit{The rules in the register set now apply to location L1.}
2993 \textit{For an example, see
2994 Appendix \refersec{app:callframeinformationexample}.}
2998 \subsection{Call Frame Calling Address}
2999 \label{chap:callframecallingaddress}
3005 unwinding frames, consumers frequently wish to obtain the
3006 address of the instruction which called a subroutine. This
3007 information is not always provided. Typically, however,
3008 one of the registers in the virtual unwind table is the
3011 If a Return Address register is defined in the virtual
3012 unwind table, and its rule is undefined (for example, by
3013 \DWCFAundefined), then there is no return address and no
3014 call address, and the virtual unwind of stack activations
3015 \addtoindexx{activation of call frame}
3018 \textit{In most cases the return address is in the same context as the
3019 calling address, but that need not be the case, especially if
3020 the producer knows in some way the call never will return. The
3021 context of the 'return address' might be on a different line,
3022 in a different lexical \livelink{chap:lexicalblock}{block},
3023 or past the end of the calling
3024 subroutine. If a consumer were to assume that it was in the
3025 same context as the calling address, the
3032 \textit{For architectures with constant-length instructions where
3033 the return address immediately follows the call instruction,
3034 a simple solution is to subtract the length of an instruction
3035 from the return address to obtain the calling instruction. For
3036 architectures with variable-length instructions (for example, x86),
3037 this is not possible. However, subtracting 1 from the return
3038 address, although not guaranteed to provide the exact calling
3039 address, generally will produce an address within the same
3040 context as the calling address, and that usually is sufficient.}