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