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