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