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