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