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