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