95790d33ee308ebe2c3d37cac0970433e4e3d53c
[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 \addtoindex{.debug\_info} or 
7 \addtoindex{.debug\_types} section.
8
9 In the descriptions that follow, these terms are used to
10 specify the representation of DWARF sections:
11
12 Initial length, section offset and 
13 \addtoindex{section length}, which are
14 defined in 
15 Sections \refersec{datarep:locationdescriptions} and 
16 \refersec{datarep:32bitand64bitdwarfformats}.
17
18 Sbyte, 
19 \addtoindex{ubyte}, 
20 \addtoindex{uhalf}, and 
21 \addtoindex{uword}, 
22 which 
23 \addtoindexx{sbyte}
24 are defined in 
25 Section \refersec{datarep:integerrepresentationnames}.
26
27 \section{Accelerated Access}
28 \label{chap:acceleratedaccess}
29
30 \textit{A debugger frequently needs to find the debugging information
31 \addtoindexx{accelerated access}
32 for a program entity defined outside of the compilation unit
33 where the debugged program is currently stopped. Sometimes the
34 debugger will know only the name of the entity; sometimes only
35 the address. To find the debugging information associated with
36 a global entity by name, using the DWARF debugging information
37 entries alone, a debugger would need to run through all
38 entries at the highest scope within each compilation unit.}
39
40 \textit{Similarly, in languages in which the name of a type is
41 required to always refer to the same concrete type (such as
42 C++), a compiler may choose to elide type definitions in
43 all compilation units except one. In this case a debugger
44 needs a rapid way of locating the concrete type definition
45 by name. As with the definition of global data objects, this
46 would require a search of all the top level type definitions
47 of all compilation units in a program.}
48
49 \textit{To find the debugging information associated with a subroutine,
50 given an address, a debugger can use the low and high pc
51 attributes of the compilation unit entries to quickly narrow
52 down the search, but these attributes only cover the range
53 of addresses for the text associated with a compilation unit
54 entry. To find the debugging information associated with a
55 data object, given an address, an exhaustive search would be
56 needed. Furthermore, any search through debugging information
57 entries for different compilation units within a large program
58 would potentially require the access of many memory pages,
59 probably hurting debugger performance.}
60
61 To make lookups of program entities (data objects, functions
62 and types) by name or by address faster, a producer of DWARF
63 information may provide three different types of tables
64 containing information about the debugging information
65 entries owned by a particular compilation unit entry in a
66 more condensed format.
67
68 \subsection{Lookup by Name}
69
70 For lookup by name, 
71 \addtoindexx{lookup!by name}
72 two tables are maintained in separate
73 \addtoindex{accelerated access!by name}
74 object file sections named 
75 \addtoindex{.debug\_pubnames} for objects and
76 functions, and 
77 \addtoindex{.debug\_pubtypes}
78 for types. Each table consists
79 of sets of variable length entries. Each set describes the
80 names of global objects and functions, or global types,
81 respectively, whose definitions are represented by debugging
82 information entries owned by a single compilation unit.
83
84 \textit{C++ member functions with a definition in the class declaration
85 are definitions in every compilation unit containing the
86 class declaration, but if there is no concrete out\dash of\dash line
87 instance there is no need to have a 
88 \addtoindex{.debug\_pubnames} entry
89 for the member function.}
90
91 Each set begins with a header containing four values:
92 \begin{enumerate}[1. ]
93
94 \item unit\_length (initial length) \\
95 \addtoindexx{unit\_length}
96 The total length of the all of the entries for that set,
97 not including the length field itself 
98 (see Section \refersec{datarep:locationdescriptions}).
99
100 \item  version (\addtoindex{uhalf}) \\
101 A version number
102 \addtoindexx{version number!name lookup table}
103 \addtoindexx{version number!type lookup table} 
104 (see Section \refersec{datarep:namelookuptables}). 
105 This number is specific
106 to the name lookup table and is independent of the DWARF
107 version number.
108
109 \item debug\_info\_offset (section offset) \\
110 The 
111 \addtoindexx{section offset!in .debug\_pubtypes header}
112 offset 
113 \addtoindexx{section offset!in .debug\_pubtypes header}
114 from the beginning of the 
115 \addtoindex{.debug\_info} section of
116 the compilation unit header referenced by the set.
117
118 \item debug\_info\_length (section length) \\
119 \addtoindexx{section length!in .debug\_pubnames header}
120 The 
121 \addtoindexx{section length!in .debug\_pubtypes header}
122 size in bytes of the contents of the 
123 \addtoindex{.debug\_info} section
124 generated to represent that compilation unit.
125 \end{enumerate}
126
127 This header is followed by a variable number of offset/name
128 pairs. Each pair consists of the section offset from the
129 beginning of the compilation unit corresponding to the current
130 set to the debugging information entry for the given object,
131 followed by a null\dash terminated character string representing
132 the name of the object as given by the \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute
133 of the referenced debugging information entry. Each set of
134 names is terminated by an offset field containing zero (and
135 no following string).
136
137
138 In the case of the name of a function member or static data
139 member of a C++ structure, class or union, the name presented
140 in the 
141 \addtoindex{.debug\_pubnames} 
142 section is not the simple name given
143 by the \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute of the referenced debugging
144 information entry, but rather the fully qualified name of
145 the data or function member.
146
147 \subsection{Lookup by Address}
148
149 For 
150 \addtoindexx{lookup!by address}
151 lookup by address, a table is maintained in a separate
152 \addtoindex{accelerated access!by address}
153 object file section called 
154 \addtoindex{.debug\_aranges}. The table consists
155 of sets of variable length entries, each set describing the
156 portion of the program\textquoteright s address space that is covered by
157 a single compilation unit.
158
159 Each set begins with a header containing five values:
160 \begin{enumerate}[1. ]
161 \item unit\_length (initial length) \\
162 \addtoindexx{unit\_length}
163 The total length of all of the
164 entries for that set, not including the length field itself
165 (see Section \refersec{datarep:initiallengthvalues}).
166
167 \item version (\addtoindex{uhalf}) \\
168 A version number\addtoindexx{version number!address lookup table} 
169 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
170 This number is specific to the address lookup table and is
171 independent of the DWARF version number.
172
173 \item debug\_info\_offset (section offset) \\
174 The offset from the
175 \addtoindexx{section offset!in .debug\_pubnames header}
176 beginning of the \addtoindex{.debug\_info} or 
177 \addtoindex{.debug\_types} section of the
178 compilation unit header referenced by the set.
179
180 \item address\_size (\addtoindex{ubyte}) \\
181 The \addtoindex{size of an address}
182 in bytes on
183 \addtoindexx{address\_size}
184 the target architecture. For 
185 \addtoindexx{address space!segmented}
186 segmented addressing, this is
187 the size of the offset portion of the address.
188
189 \item segment\_size (\addtoindex{ubyte}) \\
190 The size of a segment selector in
191 \addtoindexx{segment\_size}
192 bytes on the target architecture. If the target system uses
193 a flat address space, this value is 0.
194
195 \end{enumerate}
196
197
198 This header is followed by a variable number of address range
199 descriptors. Each descriptor is a triple consisting of a
200 segment selector, the beginning address within that segment
201 of a range of text or data covered by some entry owned by
202 the corresponding compilation unit, followed by the non\dash zero
203 length of that range. A particular set is terminated by an
204 entry consisting of three zeroes. 
205 When the 
206 \addtoindex{segment\_size} value
207 is zero in the header, the segment selector is omitted so that
208 each descriptor is just a pair, including the terminating
209 entry. By scanning the table, a debugger can quickly decide
210 which compilation unit to look in to find the debugging
211 information for an object that has a given address.
212
213 \textit{If the range of addresses covered by the text and/or data
214 of a compilation unit is not contiguous, then there may be
215 multiple address range descriptors for that compilation unit.}
216
217
218
219
220 \section{Line Number Information}
221 \label{chap:linenumberinformation}
222 \textit{A source\dash level debugger will need to know how to
223 \addtoindexx{line number information|see{\textit{also} statement list attribute}}
224 associate locations in the source files with the corresponding
225 machine instruction addresses in the executable object or
226 the shared objects used by that executable object. Such an
227 association would make it possible for the debugger user
228 to specify machine instruction addresses in terms of source
229 locations. This would be done by specifying the line number
230 and the source file containing the statement. The debugger
231 can also use this information to display locations in terms
232 of the source files and to single step from line to line,
233 or statement to statement.}
234
235 Line number information generated for a compilation unit is
236 represented in the 
237 \addtoindex{.debug\_line} section of an object file and
238 is referenced by a corresponding compilation unit debugging
239 information entry 
240 (see Section \refersec{chap:generalsubroutineandentrypointinformation}) 
241 in the \addtoindex{.debug\_info}
242 section.
243
244 \textit{Some computer architectures employ more than one instruction
245 set (for example, the ARM 
246 \addtoindexx{ARM instruction set architecture}
247 and 
248 MIPS architectures support
249 \addtoindexx{MIPS instruction set architecture}
250 a 32\dash bit as well as a 16\dash bit instruction set). Because the
251 instruction set is a function of the program counter, it is
252 convenient to encode the applicable instruction set in the
253 \addtoindex{.debug\_line} section as well.}
254
255 \textit{If space were not a consideration, the information provided
256 in the \addtoindex{.debug\_line} 
257 section could be represented as a large
258 matrix, with one row for each instruction in the emitted
259 object code. The matrix would have columns for:}
260 \begin{itemize}
261 \item \textit{the source file name}
262 \item \textit{the source line number}
263 \item \textit{the source column number}
264 \item \textit{whether this instruction is the beginning of a \addtoindex{basic block}}
265 \item \textit{and so on}
266 \end{itemize}
267 \textit{Such a matrix, however, would be impractically large. We
268 shrink it with two techniques. First, we delete from
269 the matrix each row whose file, line, source column and
270 \addtoindex{discriminator} information 
271 is identical with that of its
272 predecessors. Any deleted row would never be the beginning of
273 a source statement. Second, we design a byte\dash coded language
274 for a state machine and store a stream of bytes in the object
275 file instead of the matrix. This language can be much more
276 compact than the matrix. When a consumer of the line number
277 information executes, it must ``run'' the state machine
278 to generate the matrix for each compilation unit it is
279 interested in.  The concept of an encoded matrix also leaves
280 room for expansion. In the future, columns can be added to the
281 matrix to encode other things that are related to individual
282 instruction addresses.}
283
284 \textit{When the set of addresses of a compilation unit cannot be
285 described as a single contiguous range, there will be a
286 separate matrix for each contiguous subrange.}
287
288 \subsection{Definitions}
289
290 The following terms are used in the description of the line
291 number information format:
292
293
294 \begin{tabular} {lp{9cm}}
295 state machine &
296 The hypothetical machine used by a consumer of the line number
297 information to expand the byte\dash coded 
298 instruction stream into a matrix of
299 line number information. \\
300
301 line number program &
302 A series of byte\dash coded 
303 line number information instructions representing
304 one compilation unit. \\
305
306 \addtoindex{basic block} &
307  A sequence of instructions where only the first instruction may be a
308 branch target and only the last instruction may transfer control. A
309 procedure invocation is defined to be an exit from a 
310 \addtoindex{basic block}.
311
312 \textit{A \addtoindex{basic block} does not 
313 necessarily correspond to a specific source code
314 construct.} \\
315
316 sequence &
317 A series of contiguous target machine instructions. One compilation unit
318 may emit multiple sequences (that is, not all instructions within a
319 compilation unit are assumed to be contiguous). \\
320 \end{tabular}
321
322 \subsection{State Machine Registers}
323 \label{chap:statemachineregisters}
324
325 The line number information state machine has the following 
326 registers:
327 \begin{longtable}{l|p{9cm}}
328   \caption{State Machine Registers } \\
329   \hline \bfseries Register name&\bfseries Meaning\\ \hline
330 \endfirsthead
331   \bfseries Register name&\bfseries Meaning\\ \hline
332 \endhead
333   \hline \emph{Continued on next page}
334 \endfoot
335   \hline
336 \endlastfoot
337 \addtoindexi{address}{address register!in line number machine}&
338 The program\dash counter value corresponding to a machine instruction
339 generated by the compiler. \\
340
341 \addtoindex{op\_index} &
342 An unsigned integer representing the index of an operation within a VLIW
343 instruction. The index of the first operation is 0. For non\dash VLIW
344 architectures, this register will always be 0.
345
346 The address and \addtoindex{op\_index} registers,
347 taken together, form an operation
348 pointer that can reference any individual operation with the instruction
349 stream. \\
350
351
352 \addtoindex{file} &
353 An unsigned integer indicating the identity of the source file
354 corresponding to a machine instruction. \\
355
356 \addtoindex{line} &
357 An unsigned integer indicating a source line number. Lines are numbered
358 beginning at 1. The compiler may emit the value 0 in cases where an
359 instruction cannot be attributed to any source line. \\
360
361 \addtoindex{column} &
362 An unsigned integer indicating a column number within a source line.
363 Columns are numbered beginning at 1. The value 0 is reserved to indicate
364 that a statement begins at the ``left edge'' of the line. \\
365
366 \addtoindex{is\_stmt} &
367 A boolean indicating that the current instruction is a recommended
368 breakpoint location. A recommended breakpoint location 
369 is intended to ``represent'' a line, a 
370 statement and/or a semantically distinct subpart of a
371 statement. \\
372
373 \addtoindex{basic\_block}  &
374 A boolean indicating that the current instruction is the beginning of a
375 \addtoindex{basic block}. \\
376
377 \addtoindex{end\_sequence} &
378 A boolean indicating that the current address is that of the first byte after
379 the end of a sequence of target machine instructions. 
380 \addtoindex{end\_sequence}
381 terminates a sequence of lines; therefore other information in the same
382 row is not meaningful. \\
383
384 \addtoindex{prologue\_end} &
385 A boolean indicating that the current address is one (of possibly many)
386 where execution should be suspended for an entry breakpoint of a
387 function. \\
388
389 \addtoindex{epilogue\_begin} &
390 A boolean indicating that the current address is one (of possibly many)
391 where execution should be suspended for an exit breakpoint of a function. \\
392
393 \addtoindex{isa} &
394 An unsigned integer whose value encodes the applicable
395 instruction set architecture for the current instruction.
396 The encoding of instruction sets should be shared by all
397 users of a given architecture. It is recommended that this
398 encoding be defined by the ABI authoring committee for each
399 architecture. \\
400
401 \addtoindex{discriminator} &
402 An unsigned integer identifying the block to which the
403 current instruction belongs. Discriminator values are assigned
404 arbitrarily by the DWARF producer and serve to distinguish
405 among multiple blocks that may all be associated with the
406 same source file, line, and column. Where only one block
407 exists for a given source position, the discriminator value
408 should be zero. \\
409 \end{longtable}
410
411 \clearpage      % Keep this sentence with the following table
412 At the beginning  of each sequence within a line number
413 program, the state of the registers is:
414
415 \begin{tabular}{lp{9cm}}
416 address & 0 \\
417 \addtoindex{op\_index} & 0 \\
418 file & 1 \\
419 line & 1 \\
420 column & 0 \\
421 \addtoindex{is\_stmt} & determined by \addtoindex{default\_is\_stmt} in the line number program header \\
422 \addtoindex{basic\_block}    & \doublequote{false} \addtoindexx{basic block} \\
423 \addtoindex{end\_sequence}   & \doublequote{false} \\
424 \addtoindex{prologue\_end}   & \doublequote{false} \\
425 \addtoindex{epilogue\_begin} & \doublequote{false} \\
426 \addtoindex{isa} & 0 \\
427 discriminator & 0 \\
428 \end{tabular}
429
430 \textit{The 
431 \addtoindex{isa} value 0 specifies that the instruction set is the
432 architecturally determined default instruction set. This may
433 be fixed by the ABI, or it may be specified by other means,
434 for example, by the object file description.}
435 \subsection{Line Number Program Instructions}
436 The state machine instructions in a line number program belong to one of three categories:
437
438 \begin{enumerate}[1. ]
439 \item special opcodes \\
440 These have a \addtoindex{ubyte} opcode field and no operands.\vspace{1ex}
441
442 \textit{Most of the instructions in a 
443 line number program are special opcodes.}
444
445 \item standard opcodes \\
446 These have a \addtoindex{ubyte} opcode field which may be followed by zero or more
447 \addtoindex{LEB128} operands (except for 
448 \mbox{\livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc},} see below).
449 The opcode implies the number of operands and their meanings, but the
450 line number program header also specifies the number of operands for
451 each standard opcode.
452
453 \item extended opcodes \\
454 These have a multiple byte format. The first byte is zero; the next bytes
455 are an unsigned LEB128\addtoindexx{LEB128!unsigned} integer giving the number of bytes in the
456 instruction itself (does not include the first zero byte or the size). The
457 remaining bytes are the instruction itself (which begins with a \addtoindex{ubyte}
458 extended opcode). \\
459 \end{enumerate}
460
461
462 \subsection{The Line Number Program Header}
463
464 The optimal encoding of line number information depends to a
465 certain degree upon the architecture of the target machine. The
466 line number program header provides information used by
467 consumers in decoding the line number program instructions for
468 a particular compilation unit and also provides information
469 used throughout the rest of the line number program.
470
471 The line number program for each compilation unit begins with
472 a header containing the following fields in order:
473
474 \begin{enumerate}[1. ]
475 \item unit\_length (initial length)  \\
476 \addtoindexx{unit\_length}
477 The size in bytes of the line number information for this
478 compilation unit, not including the unit\_length field itself
479 (see Section \refersec{datarep:initiallengthvalues}). 
480
481 \item version (\addtoindex{uhalf}) 
482 A version number\addtoindexx{version number!line number information} 
483 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
484 This number is specific to
485 the line number information and is independent of the DWARF
486 version number. 
487
488 \item header\_length  \\
489 The number of bytes following the \addtoindex{header\_length} field to the
490 beginning of the first byte of the line number program itself.
491 In the 32\dash bit DWARF format, this is a 4\dash byte unsigned
492 length; in the 64\dash bit DWARF format, this field is an
493 8\dash byte unsigned length 
494 (see Section \refersec{datarep:32bitand64bitdwarfformats}). 
495
496 \item minimum\_instruction\_length (\addtoindex{ubyte})  \\
497 \addtoindexx{minimum\_instruction\_length}
498 The size in bytes of the smallest target machine
499 instruction. Line number program opcodes that alter
500 the address and \addtoindex{op\_index} registers use this and
501 \addtoindexx{maximum\_operations\_per\_instruction}
502 maximum\-\_operations\-\_per\-\_instruction in their calculations. 
503
504 \item maximum\_operations\_per\_instruction (\addtoindex{ubyte}) \\
505 The 
506 \addtoindexx{maximum\_operations\_per\_instruction}
507 maximum number of individual operations that may be
508 encoded in an instruction. Line number program opcodes
509 that alter the address and 
510 \addtoindex{op\_index} registers use this and
511 \addtoindex{minimum\_instruction\_length}
512 in their calculations.
513 For non-VLIW
514 architectures, this field is 1, the \addtoindex{op\_index register} is always
515 0, and the operation pointer is simply the address register.
516
517 \needlines{4}
518 \item default\_is\_stmt (\addtoindex{ubyte}) \\
519 \addtoindexx{default\_is\_stmt}
520 The initial value of the \addtoindex{is\_stmt} register.  
521
522 \textit{A simple approach
523 to building line number information when machine instructions
524 are emitted in an order corresponding to the source program
525 is to set \addtoindex{default\_is\_stmt} 
526 to ``true'' and to not change the
527 value of the \addtoindex{is\_stmt} register 
528 within the line number program.
529 One matrix entry is produced for each line that has code
530 generated for it. The effect is that every entry in the
531 matrix recommends the beginning of each represented line as
532 a breakpoint location. This is the traditional practice for
533 unoptimized code.}
534
535 \textit{A more sophisticated approach might involve multiple entries in
536 the matrix for a line number; in this case, at least one entry
537 (often but not necessarily only one) specifies a recommended
538 breakpoint location for the line number. \livelink{chap:DWLNSnegatestmt}{DW\-\_LNS\-\_negate\-\_stmt}
539 opcodes in the line number program control which matrix entries
540 constitute such a recommendation and 
541 \addtoindex{default\_is\_stmt} might
542 be either ``true'' or ``false''. This approach might be
543 used as part of support for debugging optimized code.}
544
545 \item line\_base (\addtoindex{sbyte}) \\
546 \addtoindexx{line\_base}
547 This parameter affects the meaning of the special opcodes. See below.
548
549 \item line\_range (\addtoindex{ubyte}) \\
550 \addtoindexx{line\_range}
551 This parameter affects the meaning of the special opcodes. See below.
552
553 \item opcode\_base (\addtoindex{ubyte}) \\
554 The 
555 \addtoindex{opcode\_base}
556 number assigned to the first special opcode.
557
558 \textit{Opcode base is typically one greater than the highest-numbered
559 \addtoindex{opcode\_base}
560 standard opcode defined for the specified version of the line
561 number information (12 in 
562 \addtoindex{DWARF Version 3} and 
563 \addtoindexx{DWARF Version 4}
564 Version 4, 9 in
565 \addtoindexx{DWARF Version 2}
566 Version 2).  
567 If opcode\_base is less than the typical value,
568 \addtoindex{opcode\_base}
569 then standard opcode numbers greater than or equal to the
570 opcode base are not used in the line number table of this unit
571 (and the codes are treated as special opcodes). If opcode\_base
572 is greater than the typical value, then the numbers between
573 that of the highest standard opcode and the first special
574 opcode (not inclusive) are used for vendor specific extensions.}
575
576 \item standard\_opcode\_lengths (array of \addtoindex{ubyte}) \\
577 \addtoindexx{standard\_opcode\_lengths}
578 This array specifies the number of \addtoindex{LEB128} operands for each
579 of the standard opcodes. The first element of the array
580 corresponds to the opcode whose value is 1, and the last
581 element corresponds to the opcode whose value 
582 is opcode\_base - 1.
583
584 By increasing opcode\_base, and adding elements to this array,
585 \addtoindex{opcode\_base}
586 new standard opcodes can be added, while allowing consumers who
587 do not know about these new opcodes to be able to skip them.
588
589 Codes for vendor specific extensions, if any, are described
590 just like standard opcodes.
591
592 \needlines{3}
593 \item include\_directories (sequence of path names) \\
594 Entries 
595 \addtoindexx{include\_directories}
596 in this sequence describe each path that was searched
597 for included source files in this compilation. (The paths
598 include those directories specified explicitly by the user for
599 the compiler to search and those the compiler searches without
600 explicit direction.) Each path entry is either a full path name
601 or is relative to the current directory of the compilation.
602
603 The last entry is followed by a single null byte.
604
605 The line number program assigns numbers to each of the file
606 entries in order, beginning with 1. The current directory of
607 the compilation is understood to be the zeroth entry and is
608 not explicitly represented.
609
610 \item  file\_names (sequence of file entries) \\
611 Entries 
612 \addtoindexx{file names}
613 in 
614 \addtoindexx{file\_names}
615 this sequence describe source files that contribute
616 to the line number information for this compilation unit or is
617 used in other contexts, such as in a declaration coordinate or
618 a macro file inclusion. Each entry consists of the following
619 values:
620
621
622 \begin{itemize}
623 \item A null\dash terminated string containing the full or relative
624 path name of a source file. If the entry contains a file
625 name or relative path name, the file is located relative
626 to either the compilation directory (as specified by the
627 \livelink{chap:DWATcompdir}{DW\-\_AT\-\_comp\-\_dir} 
628 attribute given in the compilation unit) or one
629 of the directories listed in the 
630 \addtoindex{include\_directories} section.
631
632 \item An unsigned LEB128\addtoindexx{LEB128!unsigned} 
633 number representing the directory
634 index of a directory in the 
635 \addtoindex{include\_directories} section.
636
637
638 \item An unsigned LEB128\addtoindexx{LEB128!unsigned}
639 number representing the
640 (implementation\dash defined) time of last modification for
641 the file, or 0 if not available.
642
643 \item An unsigned LEB128\addtoindexx{LEB128!unsigned} 
644 number representing the length in
645 bytes of the file, or 0 if not available.  
646
647 \end{itemize}
648
649 The last entry is followed by a single null byte.
650
651 The directory index represents an entry in the
652 \addtoindex{include\_directories} section. 
653 The index is 0 if the file was
654 found in the current directory of the compilation, 1 if it
655 was found in the first directory in the 
656 \addtoindex{include\_directories}
657 section, and so on. The directory index is ignored for file
658 names that represent full path names.
659
660 The primary source file is described by an entry whose path
661 name exactly matches that given in the \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute
662 in the compilation unit, and whose directory is understood
663 to be given by the implicit entry with index 0.
664
665 The line number program assigns numbers to each of the file
666 entries in order, beginning with 1, and uses those numbers
667 instead of file names in the file register.
668
669 \textit{A compiler may generate a single null byte for the file
670 names field and define file names using the extended opcode
671 \livelink{chap:DWLNEdefinefile}{DW\-\_LNE\-\_define\-\_file}.}
672
673
674 \end{enumerate}
675
676 \subsection{The Line Number Program}
677
678 As stated before, the goal of a line number program is to build
679 a matrix representing one compilation unit, which may have
680 produced multiple sequences of target machine instructions.
681 Within a sequence, addresses 
682 \addtoindexx{operation pointer}
683 (operation pointers) may only
684 increase. (Line numbers may decrease in cases of pipeline
685 scheduling or other optimization.)
686
687 \subsubsection{Special Opcodes} 
688 \label{chap:specialopcodes}
689 Each \addtoindex{ubyte} special opcode has the following effect on the state machine:
690
691 \begin{enumerate}[1. ]
692
693 \item  Add a signed integer to the line register.
694
695 \item  Modify the \addtoindex{operation pointer} by incrementing the
696 address and \addtoindex{op\_index} registers as described below.
697
698 \item  Append a row to the matrix using the current values
699 of the state machine registers.
700
701 \item  Set the \addtoindex{basic\_block} register to ``false.'' \addtoindexx{basic block}
702 \item  Set the \addtoindex{prologue\_end} register to ``false.''
703 \item  Set the \addtoindex{epilogue\_begin} register to ``false.''
704 \item  Set the \addtoindex{discriminator} register to 0.
705
706 \end{enumerate}
707
708 All of the special opcodes do those same seven things; they
709 differ from one another only in what values they add to the
710 line, address and \addtoindex{op\_index} registers.
711
712
713 \textit{Instead of assigning a fixed meaning to each special opcode,
714 the line number program uses several parameters in the header
715 to configure the instruction set. There are two reasons
716 for this.  First, although the opcode space available for
717 special opcodes now ranges from 13 through 255, the lower
718 bound may increase if one adds new standard opcodes. Thus, the
719 opcode\_base field of the line number program header gives the
720 value of the first special opcode. Second, the best choice of
721 special\dash opcode meanings depends on the target architecture. For
722 example, for a RISC machine where the compiler\dash generated code
723 interleaves instructions from different lines to schedule
724 the pipeline, it is important to be able to add a negative
725 value to the line register to express the fact that a later
726 instruction may have been emitted for an earlier source
727 line. For a machine where pipeline scheduling never occurs,
728 it is advantageous to trade away the ability to decrease
729 the line register (a standard opcode provides an alternate
730 way to decrease the line number) in return for the ability
731 to add larger positive values to the address register. To
732 permit this variety of strategies, the line number program
733 header defines a 
734 \addtoindexx{line\_base}
735 field that specifies the minimum
736 value which a special opcode can add to the line register
737 and a line\_range field that defines the range of values it
738 can add to the line register.}
739
740
741 A special opcode value is chosen based on the amount that needs
742 to be added to the line, address and \addtoindex{op\_index} registers.
743 The
744 maximum line increment for a special opcode is the value
745 of the 
746 \addtoindexx{line\_base}
747 field in the header, plus the value of
748 the line\_range field, minus 1 (line base + 
749 line range - 1). 
750 If the desired line increment is greater than the maximum
751 line increment, a standard opcode must be used instead of a
752 special opcode. The \addtoindex{operation advance} represents the number
753 of operations to skip when advancing the \addtoindex{operation pointer}.
754
755 The special opcode is then calculated using the following formula:
756 \begin{alltt}
757   opcode = 
758     (\textit{desired line increment} - \addtoindex{line\_base}) +
759       (\addtoindex{line\_range} * \textit{operation advance}) + \addtoindex{opcode\_base}
760 \end{alltt}
761 If the resulting opcode is greater than 255, a standard opcode
762 must be used instead.
763
764 When \addtoindex{maximum\_operations\_per\_instruction} is 1, the operation
765 advance is simply the address increment divided by the
766 \addtoindex{minimum\_instruction\_length}.
767
768 To decode a special opcode, subtract the opcode\_base from
769 the opcode itself to give the \textit{adjusted opcode}. 
770 The \textit{operation advance} 
771 is the result of the adjusted opcode divided by the
772 line\_range. The new address and \addtoindex{op\_index} values
773 are given by
774 \begin{alltt}
775   \textit{adjusted opcode} = opcode \dash opcode\_base
776   \textit{operation advance} = \textit{adjusted opcode} / line\_range
777
778   new address = address +
779     \addtoindex{minimum\_instruction\_length} *
780       ((\addtoindex{op\_index} + \addtoindex{operation advance}) / \addtoindex{maximum\_operations\_per\_instruction})
781
782   new op\_index =
783     (\addtoindex{op\_index} + \addtoindex{operation advance}) \% \addtoindex{maximum\_operations\_per\_instruction}
784 \end{alltt}
785
786 \textit{When the \addtoindex{maximum\_operations\_per\_instruction} field is 1,
787 op\_index is always 0 and these calculations simplify to those
788 given for addresses in 
789 \addtoindex{DWARF Version 3}.}
790
791 The amount to increment the line register is the 
792 \addtoindex{line\_base} plus
793 the result of the 
794 \addtoindex{adjusted opcode} modulo the 
795 \addtoindex{line\_range}. That
796 is,
797
798 \begin{alltt}
799   line increment = \addtoindex{line\_base} + (\textit{adjusted opcode} \% \addtoindex{line\_range})
800 \end{alltt}
801
802 \textit{As an example, suppose that the opcode\_base is 13, 
803 \addtoindex{line\_base}
804 is -3, \addtoindex{line\_range} is 12, 
805 \addtoindex{minimum\_instruction\_length} is 1
806 and 
807 \addtoindex{maximum\_operations\_per\_instruction} is 1. 
808 This means that
809 we can use a special opcode whenever two successive rows in
810 the matrix have source line numbers differing by any value
811 within the range [-3, 8] and (because of the limited number
812 of opcodes available) when the difference between addresses
813 is within the range [0, 20], but not all line advances are
814 available for the maximum \addtoindex{operation advance} (see below).}
815
816 \textit{The resulting opcode mapping is shown in
817 Figure \refersec{fig:examplelinenumberspecialopcodemapping}.}
818
819 \begin{figure}[ht]
820 \begin{alltt}\textit{
821                         Line Advance
822    Operation  
823      Advance    -3  -2  -1   0   1   2   3   4   5   6   7   8
824    ---------   -----------------------------------------------
825            0    13  14  15  16  17  18  19  20  21  22  23  24
826            1    25  26  27  28  29  30  31  32  33  34  35  36
827            2    37  38  39  40  41  42  43  44  45  46  47  48
828            3    49  50  51  52  53  54  55  56  57  58  59  60
829            4    61  62  63  64  65  66  67  68  69  70  71  72
830            5    73  74  75  76  77  78  79  80  81  82  83  84
831            6    85  86  87  88  89  90  91  92  93  94  95  96
832            7    97  98  99 100 101 102 103 104 105 106 107 108
833            8   109 110 111 112 113 114 115 116 117 118 119 120
834            9   121 122 123 124 125 126 127 128 129 130 131 132
835           10   133 134 135 136 137 138 139 140 141 142 143 144
836           11   145 146 147 148 149 150 151 152 153 154 155 156
837           12   157 158 159 160 161 162 163 164 165 166 167 168
838           13   169 170 171 172 173 174 175 176 177 178 179 180
839           14   181 182 183 184 185 186 187 188 189 190 191 192
840           15   193 194 195 196 197 198 199 200 201 202 203 204
841           16   205 206 207 208 209 210 211 212 213 214 215 216
842           17   217 218 219 220 221 222 223 224 225 226 227 228 
843           18   229 230 231 232 233 234 235 236 237 238 239 240 
844           19   241 242 243 244 245 246 247 248 249 250 251 252
845           20   253 254 255
846 }\end{alltt}
847 \caption{Example line number special opcode mapping}
848 \label{fig:examplelinenumberspecialopcodemapping}
849 \end{figure}
850
851 \textit{There is no requirement that the expression 
852 255 - \addtoindex{line\_base} + 1 be an integral multiple of
853 \addtoindex{line\_range}. }
854
855 \subsubsection{Standard Opcodes}
856 \label{chap:standardopcodes}
857
858
859 The standard opcodes, their applicable operands and the
860 actions performed by these opcodes are as follows:
861
862 \begin{enumerate}[1. ]
863
864 \item \textbf{DW\-\_LNS\-\_copy} \\
865 The \livetarg{chap:DWLNScopy}{DW\-\_LNS\-\_copy} 
866 opcode takes no operands. It appends a row
867 to the matrix using the current values of the state machine
868 registers. Then it sets the \addtoindex{discriminator} register to 0,
869 and sets the \addtoindex{basic\_block}, 
870 \addtoindex{prologue\_end} and 
871 \addtoindex{epilogue\_begin}
872 registers to ``false.''
873
874 \item \textbf{DW\-\_LNS\-\_advance\-\_pc} \\
875 The \livetarg{chap:DWLNSadvancepc}{DW\-\_LNS\-\_advance\-\_pc} 
876 opcode takes a single unsigned LEB128\addtoindexx{LEB128!unsigned}
877 operand as the \addtoindex{operation advance} and modifies the address
878 and \addtoindex{op\_index} registers as specified in 
879 Section \refersec{chap:specialopcodes}.
880
881 \item \textbf{DW\-\_LNS\-\_advance\-\_line} \\
882 The \livetarg{chap:DWLNSadvanceline}{DW\-\_LNS\-\_advance\-\_line} 
883 opcode takes a single signed LEB128\addtoindexx{LEB128!signed}
884 operand and adds that value to the line register of the
885 state machine.
886
887 \needlines{4}
888 \item \textbf{DW\-\_LNS\-\_set\-\_file} \\ 
889 The \livetarg{chap:DWLNSsetfile}{DW\-\_LNS\-\_set\-\_file} opcode takes a single
890 unsigned LEB128\addtoindexx{LEB128!unsigned} 
891 operand and stores it in the file register
892 of the state machine.
893
894 \item \textbf{DW\-\_LNS\-\_set\-\_column} \\ 
895 The \livetarg{chap:DWLNSsetcolumn}{DW\-\_LNS\-\_set\-\_column} opcode takes a
896 single unsigned LEB128\addtoindexx{LEB128!unsigned} operand and stores it in the column
897 register of the state machine.
898
899 \needlines{4}
900 \item \textbf{DW\-\_LNS\-\_negate\-\_stmt} \\
901 The \livetarg{chap:DWLNSnegatestmt}{DW\-\_LNS\-\_negate\-\_stmt} opcode takes no
902 operands. It sets the \addtoindex{is\_stmt} register of the state machine
903 to the logical negation of its current value.
904
905 \needlines{4}
906 \item \textbf{DW\-\_LNS\-\_set\-\_basic\-\_block} \\
907 The \livetarg{chap:DWLNSsetbasicblock}{DW\-\_LNS\-\_set\-\_basic\-\_block}
908 opcode
909 \addtoindexx{basic block}
910 takes no operands. 
911 It sets the basic\_block register of the
912 state machine to ``true.''
913
914
915
916 \item \textbf{DW\-\_LNS\-\_const\-\_add\-\_pc} \\
917 The \livetarg{chap:DWLNSconstaddpc}{DW\-\_LNS\-\_const\-\_add\-\_pc} opcode takes
918 no operands. It advances the address and op\_index registers
919 by the increments corresponding to special opcode 255.
920
921 \textit{When the line number program needs to advance the address
922 by a small amount, it can use a single special opcode,
923 which occupies a single byte. When it needs to advance the
924 address by up to twice the range of the last special opcode,
925 it can use \livelink{chap:DWLNSconstaddpc}{DW\-\_LNS\-\_const\-\_add\-\_pc} followed by a special opcode,
926 for a total of two bytes. Only if it needs to advance the
927 address by more than twice that range will it need to use
928 both \livelink{chap:DWLNSadvancepc}{DW\-\_LNS\-\_advance\-\_pc} and a special opcode, requiring three
929 or more bytes.}
930
931 \item \textbf{DW\-\_LNS\-\_fixed\-\_advance\-\_pc} \\ 
932 The \livetarg{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc} opcode
933 takes a single \addtoindex{uhalf} (unencoded) operand and adds it to the
934 address register of the state machine and sets the op\_index
935 register to 0. This is the only standard opcode whose operand
936 is \textbf{not} a variable length number. It also does 
937 \textbf{not} multiply the
938 operand by the \addtoindex{minimum\_instruction\_length} field of the header.
939
940 \textit{Existing assemblers cannot emit 
941 \livelink{chap:DWLNSadvancepc}{DW\-\_LNS\-\_advance\-\_pc} or special
942 opcodes because they cannot encode \addtoindex{LEB128} numbers or judge when
943 the computation of a special opcode overflows and requires
944 the use of \livelink{chap:DWLNSadvancepc}{DW\-\_LNS\-\_advance\-\_pc}. Such assemblers, however, can
945 use \livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc} instead, sacrificing compression.}
946
947 \item \textbf{DW\-\_LNS\-\_set\-\_prologue\-\_end} \\
948 The \livetarg{chap:DWLNSsetprologueend}{DW\-\_LNS\-\_set\-\_prologue\-\_end}
949 opcode takes no operands. It sets the 
950 \addtoindex{prologue\_end} register
951 to ``true''.
952
953 \textit{When a breakpoint is set on entry to a function, it is
954 generally desirable for execution to be suspended, not on the
955 very first instruction of the function, but rather at a point
956 after the function's frame has been set up, after any language
957 defined local declaration processing has been completed,
958 and before execution of the first statement of the function
959 begins. Debuggers generally cannot properly determine where
960 this point is. This command allows a compiler to communicate
961 the location(s) to use.}
962
963 \textit{In the case of optimized code, there may be more than one such
964 location; for example, the code might test for a special case
965 and make a fast exit prior to setting up the frame.}
966
967 \textit{Note that the function to which the 
968 \addtoindex{prologue end} applies cannot
969 be directly determined from the line number information alone;
970 it must be determined in combination with the subroutine
971 information entries of the compilation (including inlined
972 subroutines).}
973
974
975 \item \textbf{DW\-\_LNS\-\_set\-\_epilogue\-\_begin} \\
976 The \livetarg{chap:DWLNSsetepiloguebegin}{DW\-\_LNS\-\_set\-\_epilogue\-\_begin} opcode takes no operands. It
977 sets the \addtoindex{epilogue\_begin} register to ``true''.
978
979 \textit{When a breakpoint is set on the exit of a function or execution
980 steps over the last executable statement of a function, it is
981 generally desirable to suspend execution after completion of
982 the last statement but prior to tearing down the frame (so that
983 local variables can still be examined). Debuggers generally
984 cannot properly determine where this point is. This command
985 allows a compiler to communicate the location(s) to use.}
986
987 \textit{Note that the function to which the 
988 \addtoindex{epilogue end} applies cannot
989 be directly determined from the line number information alone;
990 it must be determined in combination with the subroutine
991 information entries of the compilation (including inlined
992 subroutines).}
993
994 \textit{In the case of a trivial function, both 
995 \addtoindex{prologue end} and
996 \addtoindex{epilogue begin} may occur at the same address.}
997
998 \item \textbf{DW\-\_LNS\-\_set\-\_isa} \\
999 The \livetarg{chap:DWLNSsetisa}{DW\-\_LNS\-\_set\-\_isa} opcode takes a single
1000 unsigned LEB128\addtoindexx{LEB128!unsigned} operand and stores that value in the 
1001 \addtoindex{isa}
1002 register of the state machine.
1003 \end{enumerate}
1004
1005 \subsubsection{ExtendedOpcodes}
1006 \label{chap:extendedopcodes}
1007
1008 The extended opcodes are as follows:
1009
1010 \begin{enumerate}[1. ]
1011
1012 \item \textbf{DW\-\_LNE\-\_end\-\_sequence} \\
1013 The \livetarg{chap:DWLNEendsequence}{DW\-\_LNE\-\_end\-\_sequence} opcode takes no operands. It sets the
1014 \addtoindex{end\_sequence}
1015 register of the state machine to \doublequote{true} and
1016 appends a row to the matrix using the current values of the
1017 state-machine registers. Then it resets the registers to the
1018 initial values specified above 
1019 (see Section \refersec{chap:statemachineregisters}). 
1020 Every line
1021 number program sequence must end with a \livelink{chap:DWLNEendsequence}{DW\-\_LNE\-\_end\-\_sequence}
1022 instruction which creates a row whose address is that of the
1023 byte after the last target machine instruction of the sequence.
1024
1025 \needlines{5}
1026 \item \textbf{DW\-\_LNE\-\_set\-\_address} \\
1027 The \livetarg{chap:DWLNEsetaddress}{DW\-\_LNE\-\_set\-\_address} opcode takes a single relocatable
1028 address as an operand. The size of the operand is the size
1029 of an address on the target machine. It sets the address
1030 register to the value given by the relocatable address and
1031 sets the op\_index register to 0.
1032
1033 \textit{All of the other line number program opcodes that
1034 affect the address register add a delta to it. This instruction
1035 stores a relocatable value into it instead.}
1036
1037 \needlines{4}
1038 \item \textbf{DW\-\_LNE\-\_define\-\_file} \\
1039
1040 The \livetarg{chap:DWLNEdefinefile}{DW\-\_LNE\-\_define\-\_file} opcode takes four operands:
1041 \begin{enumerate}[1. ]
1042
1043 \item A null\dash terminated string containing the full or relative
1044 path name of a source file. If the entry contains a file
1045 name or a relative path name, the file is located relative
1046 to either the compilation directory (as specified by the
1047 \livelink{chap:DWATcompdir}{DW\-\_AT\-\_comp\-\_dir} attribute given in the compilation unit)
1048 or one of the directories in the 
1049 \addtoindex{include\_directories} section.
1050
1051 \item An unsigned LEB128\addtoindexx{LEB128!unsigned} 
1052 number representing the directory index
1053 of the directory in which the file was found.  
1054
1055 \item An unsigned LEB128\addtoindexx{LEB128!unsigned} 
1056 number representing the time of last modification
1057 of the file, or 0 if not available.  
1058
1059 \item An unsigned LEB128\addtoindexx{LEB128!unsigned}
1060 number representing the length in bytes of the file, or 0 if
1061 not available.
1062 \end{enumerate}
1063
1064 The directory index represents an entry in the
1065 \addtoindex{include\_directories} section of the line number program
1066 header. The index is 0 if the file was found in the current
1067 directory of the compilation, 1 if it was found in the first
1068 directory in the \addtoindex{include\_directories} section,
1069 and so on. The
1070 directory index is ignored for file names that represent full
1071 path names.
1072
1073 The primary source file is described by an entry whose path
1074 name exactly matches that given in the \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute
1075 in the compilation unit, and whose directory index is 0. The
1076 files are numbered, starting at 1, in the order in which they
1077 appear; the names in the header come before names defined by
1078 the \livelink{chap:DWLNEdefinefile}{DW\-\_LNE\-\_define\-\_file} instruction. These numbers are used
1079 in the file register of the state machine.
1080
1081 \item \textbf{DW\-\_LNE\-\_set\-\_discriminator} \\
1082 The \livetarg{chap:DWLNEsetdiscriminator}{DW\-\_LNE\-\_set\-\_discriminator}
1083 opcode takes a single
1084 parameter, an unsigned LEB128\addtoindexx{LEB128!unsigned} 
1085 integer. It sets the
1086 \addtoindex{discriminator} register to the new value.
1087
1088 \end{enumerate}
1089
1090 \textit{Appendix \refersec{app:linenumberprogramexample} 
1091 gives some sample line number programs.}
1092
1093 \section{Macro Information}
1094 \label{chap:macroinformation}
1095 \textit{Some languages, such as 
1096 \addtoindex{C} and 
1097 \addtoindex{C++}, provide a way to replace
1098 \addtoindex{macro information}
1099 text in the source program with macros defined either in the
1100 source file itself, or in another file included by the source
1101 file.  Because these macros are not themselves defined in the
1102 target language, it is difficult to represent their definitions
1103 using the standard language constructs of DWARF. The debugging
1104 information therefore reflects the state of the source after
1105 the macro definition has been expanded, rather than as the
1106 programmer wrote it. The macro information table provides a way
1107 of preserving the original source in the debugging information.}
1108
1109 As described in 
1110 Section \refersec{chap:normalandpartialcompilationunitentries},
1111 the macro information for a
1112 given compilation unit is represented in the 
1113 \addtoindex{.debug\_macinfo}
1114 section of an object file. The macro information for each
1115 compilation unit is represented as a series of \doublequote{macinfo}
1116 entries. Each macinfo entry consists of a \doublequote{type code} and
1117 up to two additional operands. The series of entries for a
1118 given compilation unit ends with an entry containing a type
1119 code of 0.
1120
1121 \subsection{Macinfo Types}
1122 \label{chap:macinfotypes}
1123
1124 The valid \addtoindex{macinfo types} are as follows:
1125
1126 \begin{tabular}{ll}
1127 \livelink{chap:DWMACINFOdefine}{DW\-\_MACINFO\-\_define} 
1128 &A macro definition\\
1129 \livelink{chap:DWMACINFOundef}{DW\-\_MACINFO\-\_undef}
1130 &A macro undefinition\\
1131 \livelink{chap:DWMACINFOstartfile}{DW\-\_MACINFO\-\_start\-\_file}
1132 &The start of a new source file inclusion\\
1133 \livelink{chap:DWMACINFOendfile}{DW\-\_MACINFO\-\_end\-\_file}
1134 &The end of the current source file inclusion\\
1135 \livelink{chap:DWMACINFOvendorext}{DW\-\_MACINFO\-\_vendor\-\_ext}
1136 & Vendor specific macro information directives\\
1137 \end{tabular}
1138
1139 \subsubsection{Define and Undefine Entries}
1140 \label{chap:defineandundefineentries}
1141
1142 All 
1143 \livetarg{chap:DWMACINFOdefine}{DW\-\_MACINFO\-\_define} and 
1144 \livetarg{chap:DWMACINFOundef}{DW\-\_MACINFO\-\_undef} entries have two
1145 operands. The first operand encodes the line number of the
1146 source line on which the relevant defining or undefining
1147 macro directives appeared.
1148
1149 The second operand consists of a null-terminated character
1150 string. In the case of a 
1151 \livelink{chap:DWMACINFOundef}{DW\-\_MACINFO\-\_undef} entry, the value
1152 of this string will be simply the name of the pre- processor
1153 symbol that was undefined at the indicated source line.
1154
1155 In the case of a \livelink{chap:DWMACINFOdefine}{DW\-\_MACINFO\-\_define} entry, the value of this
1156 string will be the name of the macro symbol that was defined
1157 at the indicated source line, followed immediately by the 
1158 \addtoindex{macro formal parameter list}
1159 including the surrounding parentheses (in
1160 the case of a function-like macro) followed by the definition
1161 string for the macro. If there is no formal parameter list,
1162 then the name of the defined macro is followed directly by
1163 its definition string.
1164
1165 In the case of a function-like macro definition, no whitespace
1166 characters should appear between the name of the defined
1167 macro and the following left parenthesis. Also, no whitespace
1168 characters should appear between successive formal parameters
1169 in the formal parameter list. (Successive formal parameters
1170 are, however, separated by commas.) Also, exactly one space
1171 character should separate the right parenthesis that terminates
1172 the formal parameter list and the following definition string.
1173
1174 In the case of a ``normal'' (i.e. non-function-like) macro
1175 definition, exactly one space character should separate the
1176 name of the defined macro from the following definition text.
1177
1178
1179
1180 \subsubsection{Start File Entries}
1181 \label{chap:startfileentries}
1182 Each \livetarg{chap:DWMACINFOstartfile}{DW\-\_MACINFO\-\_start\-\_file} entry also has two operands. The
1183 first operand encodes the line number of the source line on
1184 which the inclusion macro directive occurred.
1185
1186 The second operand encodes a source file name index. This index
1187 corresponds to a file number in the line number information
1188 table for the relevant compilation unit. This index indicates
1189 (indirectly) the name of the file that is being included by
1190 the inclusion directive on the indicated source line.
1191
1192 \subsubsection{End File Entries}
1193 \label{chap:endfileentries}
1194 A \livetarg{chap:DWMACINFOendfile}{DW\-\_MACINFO\-\_end\-\_file} entry has no operands. The presence of
1195 the entry marks the end of the current source file inclusion.
1196
1197 \subsubsection{Vendor Extension Entries}
1198 \label{chap:vendorextensionentries}
1199 A \livetarg{chap:DWMACINFOvendorext}{DW\-\_MACINFO\-\_vendor\-\_ext} entry has two operands. The first
1200 is a constant. The second is a null-terminated character
1201 string. The meaning and/or significance of these operands is
1202 intentionally left undefined by this specification.
1203
1204 \textit{A consumer must be able to totally ignore all
1205 \livelink{chap:DWMACINFOvendorext}{DW\-\_MACINFO\-\_vendor\-\_ext} entries that it does not understand
1206 (see Section \refersec{datarep:vendorextensibility}).}
1207
1208
1209 \subsection{Base Source Entries} 
1210 \label{chap:basesourceentries}
1211
1212 A producer shall generate \livelink{chap:DWMACINFOstartfile}{DW\-\_MACINFO\-\_start\-\_file} and
1213 \livelink{chap:DWMACINFOendfile}{DW\-\_MACINFO\-\_end\-\_file} entries for the source file submitted to
1214 the compiler for compilation. This \livelink{chap:DWMACINFOstartfile}{DW\-\_MACINFO\-\_start\-\_file} entry
1215 has the value 0 in its line number operand and references
1216 the file entry in the line number information table for the
1217 primary source file.
1218
1219
1220 \subsection{Macinfo Entries For Command Line Options}
1221 \label{chap:macinfoentriesforcommandlineoptions}
1222
1223 In addition to producing \livelink{chap:DWMACINFOdefine}{DW\-\_MACINFO\-\_define} and \livelink{chap:DWMACINFOundef}{DW\-\_MACINFO\-\_undef}
1224 entries for each of the define and undefine directives
1225 processed during compilation, the DWARF producer should
1226 generate a \livelink{chap:DWMACINFOdefine}{DW\-\_MACINFO\-\_define} or \livelink{chap:DWMACINFOundef}{DW\-\_MACINFO\-\_undef} entry for
1227 each pre-processor symbol which is defined or undefined by
1228 some means other than via a define or undefine directive
1229 within the compiled source text. In particular, pre-processor
1230 symbol definitions and un- definitions which occur as a
1231 result of command line options (when invoking the compiler)
1232 should be represented by their own \livelink{chap:DWMACINFOdefine}{DW\-\_MACINFO\-\_define} and
1233 \livelink{chap:DWMACINFOundef}{DW\-\_MACINFO\-\_undef} entries.
1234
1235 All such \livelink{chap:DWMACINFOdefine}{DW\-\_MACINFO\-\_define} and \livelink{chap:DWMACINFOundef}{DW\-\_MACINFO\-\_undef} entries
1236 representing compilation options should appear before the
1237 first \livelink{chap:DWMACINFOstartfile}{DW\-\_MACINFO\-\_start\-\_file} entry for that compilation unit
1238 and should encode the value 0 in their line number operands.
1239
1240
1241 \subsection{General rules and restrictions}
1242 \label{chap:generalrulesandrestrictions}
1243
1244 All macinfo entries within a \addtoindex{.debug\_macinfo}
1245 section for a
1246 given compilation unit appear in the same order in which the
1247 directives were processed by the compiler.
1248
1249 All macinfo entries representing command line options appear
1250 in the same order as the relevant command line options
1251 were given to the compiler. In the case where the compiler
1252 itself implicitly supplies one or more macro definitions or
1253 un-definitions in addition to those which may be specified on
1254 the command line, macinfo entries are also produced for these
1255 implicit definitions and un-definitions, and these entries
1256 also appear in the proper order relative to each other and
1257 to any definitions or undefinitions given explicitly by the
1258 user on the command line.
1259
1260
1261 \needlines{6}
1262 \section{Call Frame Information}
1263 \label{chap:callframeinformation}
1264
1265 \textit{Debuggers often need to be able to view and modify the state of any subroutine activation that is
1266 \addtoindexx{activation!call frame}
1267 on the call stack. An activation consists of:}
1268
1269 \begin{itemize}
1270 \item \textit{A code location that is within the
1271 subroutine. This location is either the place where the program
1272 stopped when the debugger got control (e.g. a breakpoint), or
1273 is a place where a subroutine made a call or was interrupted
1274 by an asynchronous event (e.g. a signal).}
1275
1276 \item \textit{An area of memory that is allocated on a stack called a
1277 ``call frame.'' The call frame is identified by an address
1278 on the stack. We refer to this address as the Canonical
1279 Frame Address or CFA. Typically, the CFA is defined to be the
1280 value of the stack pointer at the call site in the previous
1281 frame (which may be different from its value on entry to the
1282 current frame).}
1283
1284 \item \textit{A set of registers that are in use by the subroutine
1285 at the code location.}
1286
1287 \end{itemize}
1288
1289 \textit{Typically, a set of registers are designated to be preserved
1290 across a call. If a callee wishes to use such a register, it
1291 saves the value that the register had at entry time in its call
1292 frame and restores it on exit. The code that allocates space
1293 on the call frame stack and performs the save operation is
1294 called the subroutine\textquoteright s \addtoindex{prologue}, and the code that performs
1295 the restore operation and deallocates the frame is called its
1296 \addtoindex{epilogue}. Typically, the 
1297 \addtoindex{prologue} code is physically at the
1298 beginning of a subroutine and the 
1299 \addtoindex{epilogue} code is at the end.}
1300
1301 \textit{To be able to view or modify an activation that is not
1302 on the top of the call frame stack, the debugger must
1303 ``virtually unwind'' the stack of activations until
1304 it finds the activation of interest.  A debugger unwinds
1305 a stack in steps. Starting with the current activation it
1306 virtually restores any registers that were preserved by the
1307 current activation and computes the predecessor\textquoteright s CFA and
1308 code location. This has the logical effect of returning from
1309 the current subroutine to its predecessor. We say that the
1310 debugger virtually unwinds the stack because the actual state
1311 of the target process is unchanged.}
1312
1313 \textit{The unwinding operation needs to know where registers are
1314 saved and how to compute the predecessor\textquoteright s CFA and code
1315 location. When considering an architecture-independent way
1316 of encoding this information one has to consider a number of
1317 special things.}
1318
1319
1320 \begin{itemize} % bullet list
1321
1322 \item \textit{Prologue 
1323 \addtoindexx{prologue}
1324 and 
1325 \addtoindex{epilogue} code is not always in 
1326 distinct block
1327 at the beginning and end of a subroutine. It is common
1328 to duplicate the \addtoindex{epilogue} code 
1329 at the site of each return
1330 from the code. Sometimes a compiler breaks up the register
1331 save/unsave operations and moves them into the body of the
1332 subroutine to just where they are needed.}
1333
1334
1335 \item \textit{Compilers use different ways to manage the call
1336 frame. Sometimes they use a frame pointer register, sometimes
1337 not.}
1338
1339 \item \textit{The algorithm to compute CFA changes as you progress through
1340 the \addtoindex{prologue} 
1341 and \addtoindex{epilogue code}. 
1342 (By definition, the CFA value
1343 does not change.)}
1344
1345 \item \textit{Some subroutines have no call frame.}
1346
1347 \item \textit{Sometimes a register is saved in another register that by
1348 convention does not need to be saved.}
1349
1350 \item \textit{Some architectures have special instructions that perform
1351 some or all of the register management in one instruction,
1352 leaving special information on the stack that indicates how
1353 registers are saved.}
1354
1355 \item \textit{Some architectures treat return address values specially. For
1356 example, in one architecture, the call instruction guarantees
1357 that the low order two bits will be zero and the return
1358 instruction ignores those bits. This leaves two bits of
1359 storage that are available to other uses that must be treated
1360 specially.}
1361
1362
1363 \end{itemize}
1364
1365
1366 \subsection{Structure of Call Frame Information}
1367 \label{chap:structureofcallframeinformation}
1368
1369 DWARF supports virtual unwinding by defining an architecture
1370 independent basis for recording how procedures save and restore
1371 registers during their lifetimes. This basis must be augmented
1372 on some machines with specific information that is defined by
1373 an architecture specific ABI authoring committee, a hardware
1374 vendor, or a compiler producer. The body defining a specific
1375 augmentation is referred to below as the ``augmenter.''
1376
1377 Abstractly, this mechanism describes a very large table that
1378 has the following structure:
1379
1380 \begin{verbatim}
1381         LOC CFA R0 R1 ... RN
1382         L0
1383         L1
1384         ...
1385         LN
1386 \end{verbatim}
1387
1388
1389 The first column indicates an address for every location
1390 that contains code in a program. (In shared objects, this
1391 is an object-relative offset.) The remaining columns contain
1392 virtual unwinding rules that are associated with the indicated
1393 location.
1394
1395 The CFA column defines the rule which computes the Canonical
1396 Frame Address value; it may be either a register and a signed
1397 offset that are added together, or a DWARF expression that
1398 is evaluated.
1399
1400 The remaining columns are labeled by register number. This
1401 includes some registers that have special designation on
1402 some architectures such as the PC and the stack pointer
1403 register. (The actual mapping of registers for a particular
1404 architecture is defined by the augmenter.) The register columns
1405 contain rules that describe whether a given register has been
1406 saved and the rule to find the value for the register in the
1407 previous frame.
1408
1409 \needlines{4}
1410 The register rules are:
1411
1412 \begin{tabular}{lp{8cm}}
1413 undefined 
1414 &A register that has this rule has no recoverable value in the previous frame.
1415 (By convention, it is not preserved by a callee.) \\
1416
1417 same value
1418 &This register has not been modified from the previous frame. (By convention,
1419 it is preserved by the callee, but the callee has not modified it.) \\
1420
1421 offset(N)
1422 &The previous value of this register is saved at the address CFA+N where CFA
1423 is the current CFA value and N is a signed offset.\\
1424
1425 val\_offset(N)
1426 &The previous value of this register is the value CFA+N where CFA is the
1427 current CFA value and N is a signed offset.\\
1428
1429 register(R)
1430 &The previous value of this register is stored 
1431 in another register numbered R.\\
1432
1433 expression(E)
1434 &The previous value of this register is located at the address produced by
1435 executing the DWARF expression E.\\
1436
1437 val\_expression(E) 
1438 &The previous value of this register is the value produced by executing the
1439 DWARF expression E.\\
1440
1441 architectural
1442 &The rule is defined externally to this specification by the augmenter.\\
1443
1444 \end{tabular}
1445
1446 \textit{This table would be extremely large if actually constructed
1447 as described. Most of the entries at any point in the table
1448 are identical to the ones above them. The whole table can be
1449 represented quite compactly by recording just the differences
1450 starting at the beginning address of each subroutine in
1451 the program.}
1452
1453 The virtual unwind information is encoded in a self-contained
1454 section called 
1455 \addtoindex{.debug\_frame}.  Entries in a 
1456 \addtoindex{.debug\_frame} section
1457 are aligned on a multiple of the address size relative to
1458 the start of the section and come in two forms: a Common
1459 \addtoindexx{common information entry}
1460 Information Entry (CIE) and a 
1461 \addtoindexx{frame description entry}
1462 Frame Description Entry (FDE).
1463
1464 \textit{If the range of code addresses for a function is not
1465 contiguous, there may be multiple CIEs and FDEs corresponding
1466 to the parts of that function.}
1467
1468
1469 A Common Information Entry holds information that is shared
1470 among many Frame Description Entries. There is at least one
1471 CIE in every non-empty \addtoindex{.debug\_frame} section. A CIE contains
1472 the following fields, in order:
1473 \begin{enumerate}[1. ]
1474 \item length (initial length)  \\
1475 A constant that gives the number of bytes of the CIE structure,
1476 not including the length field itself 
1477 (see Section \refersec{datarep:initiallengthvalues}). 
1478 The
1479 size of the length field plus the value of length must be an
1480 integral multiple of the address size.
1481
1482 \item  CIE\_id (4 or 8 bytes, see Section \refersec{datarep:32bitand64bitdwarfformats}) \\
1483 A constant that is used to distinguish CIEs from FDEs.
1484
1485 \item  version (\addtoindex{ubyte}) \\
1486 A version number\addtoindexx{version number!call frame information} 
1487 (see Section \refersec{datarep:callframeinformation}). 
1488 This number is specific to the call frame information
1489 and is independent of the DWARF version number.
1490
1491
1492 \item  augmentation (\addtoindex{UTF\dash 8} string) \\
1493 A null\dash terminated UTF\dash 8 string that identifies the augmentation
1494 to this CIE or to the FDEs that use it. If a reader encounters
1495 an augmentation string that is unexpected, then only the
1496 following fields can be read:
1497
1498
1499 \begin{itemize}
1500
1501 \item CIE: length, CIE\_id, version, augmentation
1502
1503 \item FDE: length, CIE\_pointer, initial\_location, address\_range
1504
1505 \end{itemize}
1506 If there is no augmentation, this value is a zero byte.
1507
1508 \textit{The augmentation string allows users to indicate that there
1509 is additional target\dash specific information in the CIE or FDE
1510 which is needed to unwind a stack frame. For example, this
1511 might be information about dynamically allocated data which
1512 needs to be freed on exit from the routine.}
1513
1514 \textit{Because the \addtoindex{.debug\_frame} section is useful independently of
1515 any \addtoindex{.debug\_info} section, the augmentation string always uses
1516 UTF\dash 8 encoding.}
1517
1518 \item  address\_size (\addtoindex{ubyte}) \\
1519 The size of a target address
1520 \addtoindexx{address\_size}
1521 in this CIE and any FDEs that
1522 use it, in bytes. If a compilation unit exists for this frame,
1523 its address size must match the address size here.
1524
1525 \item  segment\_size (\addtoindex{ubyte}) \\
1526 The \addtoindexx{segment\_size}
1527 size of a segment selector in this CIE and any FDEs that
1528 use it, in bytes.
1529
1530 \item  \addtoindex{code\_alignment\_factor} (unsigned LEB128) 
1531 \addtoindexx{LEB128!unsigned}\addtoindexx{unsigned LEB128|see{LEB128, unsigned}}
1532 \addtoindexx{code alignment factor} \\
1533
1534 \addtoindexx{\textless caf\textgreater|see{code alignment factor}}
1535 constant that is factored out of all advance location
1536 instructions (see 
1537 Section \refersec{chap:rowcreationinstructions}).
1538
1539
1540 \item  \addtoindex{data\_alignment\_factor} (signed LEB128)
1541 \addtoindexx{LEB128!signed}\addtoindexx{signed LEB128|see{LEB128, signed}} \\
1542 \addtoindexx{data alignment factor}
1543
1544 \addtoindexx{\textless daf\textgreater|see{data alignment factor}}
1545 constant that is factored out of certain offset instructions
1546 (see below). The resulting value is  \textit{(operand *
1547 data\_alignment\_factor)}.
1548
1549 \item  return\_address\_register (unsigned LEB128)\addtoindexx{LEB128!unsigned} \\
1550 An unsigned LEB128 constant that indicates which column in the
1551 rule table represents the return address of the function. Note
1552 that this column might not correspond to an actual machine
1553 register.
1554
1555 \item initial\_instructions (array of \addtoindex{ubyte}) \\
1556 A sequence of rules that are interpreted to create the initial
1557 setting of each column in the table.  The default rule for
1558 all columns before interpretation of the initial instructions
1559 is the undefined rule. However, an ABI authoring body or a
1560 compilation system authoring body may specify an alternate
1561 default value for any or all columns.
1562
1563 \item padding (array of \addtoindex{ubyte}) \\
1564 Enough \livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop} instructions to make the size of this entry
1565 match the length value above.
1566 \end{enumerate}
1567
1568 An FDE contains the following fields, in order:
1569 \begin{enumerate}[1. ]
1570 \item length (initial length)  \\
1571
1572 A constant that gives the number of bytes of the header and
1573 instruction stream for this function, not including the length
1574 field itself 
1575 (see Section  \refersec{datarep:initiallengthvalues}). 
1576 The size of the length field
1577 plus the value of length must be an integral multiple of the
1578 address size.
1579
1580 \item   CIE\_pointer (4 or 8 bytes, see Section \refersec{datarep:32bitand64bitdwarfformats}) \\
1581 A constant 
1582 \addtoindexx{section offset!in FDE header}
1583 offset into the \addtoindex{.debug\_frame}
1584 section that denotes
1585 the CIE that is associated with this FDE.
1586
1587 \item  initial\_location (segment selector and target address) \\
1588 The 
1589 \addtoindexx{initial\_location}
1590 address of the first location associated with this table
1591 entry. 
1592 If the \addtoindex{segment\_size} field of this FDE's CIE is non-zero,
1593 the initial location is preceded by a segment selector of
1594 the given length.
1595
1596 \item  address\_range (target address) \\
1597 The 
1598 \addtoindexx{address\_range}
1599 number 
1600 \addtoindexx{target address}
1601 of bytes of program instructions described by this entry.
1602
1603 \item instructions (array of \addtoindex{ubyte}) \\
1604 A sequence of table defining instructions that are described below.
1605
1606 \item padding (array of \addtoindex{ubyte}) \\
1607 Enough \livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop} instructions 
1608 to make the size of this entry match the length value above.
1609 \end{enumerate}
1610
1611 \subsection{Call Frame Instructions}
1612 \label{chap:callframeinstructions}
1613
1614 Each call frame instruction is defined to take 0 or more
1615 operands. Some of the operands may be encoded as part of the
1616 opcode 
1617 (see Section \refersec{datarep:callframeinformation}). 
1618 The instructions are defined in
1619 the following sections.
1620
1621 Some call frame instructions have operands that are encoded
1622 as DWARF expressions 
1623 (see Section \refersec{chap:generaloperations}). 
1624 The following DWARF
1625 operators cannot be used in such operands:
1626
1627
1628 \begin{itemize}
1629 \item \livelink{chap:DWOPcall2}{DW\-\_OP\-\_call2}, \livelink{chap:DWOPcall4}{DW\-\_OP\-\_call4} 
1630 and \livelink{chap:DWOPcallref}{DW\-\_OP\-\_call\-\_ref} operators
1631 are not meaningful in an operand of these instructions
1632 because there is no mapping from call frame information to
1633 any corresponding debugging compilation unit information,
1634 thus there is no way to interpret the call offset.
1635
1636 \item \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address} is not meaningful in an operand
1637 of these instructions because there is no object context to
1638 provide a value to push.
1639
1640 \item \livelink{chap:DWOPcallframecfa}{DW\-\_OP\-\_call\-\_frame\-\_cfa} is not meaningful in an operand of
1641 these instructions because its use would be circular.
1642 \end{itemize}
1643
1644 \textit{Call frame instructions to which these restrictions apply
1645 include \livelink{chap:DWCFAdefcfaexpression}{DW\-\_CFA\-\_def\-\_cfa\-\_expression}, \livelink{chap:DWCFAexpression}{DW\-\_CFA\-\_expression}
1646 and \livelink{chap:DWCFAvalexpression}{DW\-\_CFA\-\_val\-\_expression}.}
1647
1648 \subsubsection{Row Creation Instructions}
1649 \label{chap:rowcreationinstructions}
1650 \begin{enumerate}[1. ]
1651
1652 \item \textbf{DW\-\_CFA\-\_set\-\_loc} \\
1653 The \livetarg{chap:DWCFAsetloc}{DW\-\_CFA\-\_set\-\_loc} instruction 
1654 takes a single operand that
1655 represents a target address. The required action is to create a
1656 new table row using the specified address as the location. All
1657 other values in the new row are initially identical to the
1658 current row. The new location value is always greater than
1659 the current one. 
1660 If the \addtoindex{segment\_size} field of this FDE's 
1661 \addtoindex{CIE}
1662 is non- zero, the initial location is preceded by a segment
1663 selector of the given length.
1664
1665
1666 \item \textbf{DW\-\_CFA\-\_advance\-\_loc} \\
1667 The \livetarg{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advanceloc} instruction takes a single operand (encoded
1668 with the opcode) that represents a constant delta. The required
1669 action is to create a new table row with a location value that
1670 is computed by taking the current entry\textquoteright s location value
1671 and adding the value of 
1672 \textit{delta * \addtoindex{code\_alignment\_factor}}. 
1673 All
1674 other values in the new row are initially identical to the
1675 current row
1676
1677 \item \textbf{DW\-\_CFA\-\_advance\-\_loc1} \\
1678 The \livetarg{chap:DWCFAadvanceloc1}{DW\-\_CFA\-\_advance\-\_loc1} instruction takes a single \addtoindex{ubyte}
1679 operand that represents a constant delta. This instruction
1680 is identical to \livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc} except for the encoding
1681 and size of the delta operand.
1682
1683 \item \textbf{DW\-\_CFA\-\_advance\-\_loc2} \\
1684 The \livetarg{chap:DWCFAadvanceloc2}{DW\-\_CFA\-\_advance\-\_loc2} instruction takes a single
1685 \addtoindex{uhalf}
1686 operand that represents a constant delta. This instruction
1687 is identical to \livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc} except for the encoding
1688 and size of the delta operand.
1689
1690 \item \textbf{DW\-\_CFA\-\_advance\-\_loc4} \\
1691 The \livetarg{chap:DWCFAadvanceloc4}{DW\-\_CFA\-\_advance\-\_loc4} instruction takes a single
1692 \addtoindex{uword}
1693 operand that represents a constant delta. This instruction
1694 is identical to \livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc} except for the encoding
1695 and size of the delta operand.
1696
1697 \end{enumerate}
1698
1699 \subsubsection{CFA Definition Instructions}
1700 \label{chap:cfadefinitioninstructions}
1701 \begin{enumerate}[1. ]
1702
1703 \item \textbf{DW\-\_CFA\-\_def\-\_cfa} \\
1704 The \livetarg{chap:DWCFAdefcfa}{DW\-\_CFA\-\_def\-\_cfa}
1705 instruction takes two unsigned LEB128\addtoindexx{LEB128!unsigned}
1706 operands representing a register number and a (non\dash factored)
1707 offset. The required action is to define the current CFA rule
1708 to use the provided register and offset.
1709
1710 \item \textbf{ DW\-\_CFA\-\_def\-\_cfa\-\_sf} \\
1711 The \livetarg{chap:DWCFAdefcfasf}{DW\-\_CFA\-\_def\-\_cfa\-\_sf} instruction takes two operands:
1712 an unsigned LEB128 value\addtoindexx{LEB128!unsigned}
1713 representing a register number and a
1714 signed LEB128\addtoindexx{LEB128!signed} factored offset. This instruction is identical
1715 to \livelink{chap:DWCFAdefcfa}{DW\-\_CFA\-\_def\-\_cfa} except that the second operand is signed
1716 and factored. The resulting offset is factored\_offset *
1717 \addtoindex{data\_alignment\_factor}.
1718
1719
1720 \item \textbf{DW\-\_CFA\-\_def\-\_cfa\-\_register} \\
1721 The \livetarg{chap:DWCFAdefcfaregister}{DW\-\_CFA\-\_def\-\_cfa\-\_register} 
1722 instruction takes a single
1723 unsigned LEB128\addtoindexx{LEB128!unsigned} operand representing a register number. The
1724 required action is to define the current CFA rule to use
1725 the provided register (but to keep the old offset). This
1726 operation is valid only if the current CFA rule is defined
1727 to use a register and offset.
1728
1729
1730
1731 \item \textbf{DW\-\_CFA\-\_def\-\_cfa\-\_offset} \\
1732 The \livetarg{chap:DWCFAdefcfaoffset}{DW\-\_CFA\-\_def\-\_cfa\-\_offset} instruction takes a single
1733 unsigned LEB128\addtoindexx{LEB128!unsigned} operand representing a (non-factored)
1734 offset. The required action is to define the current CFA rule
1735 to use the provided offset (but to keep the old register). This
1736 operation is valid only if the current CFA rule is defined
1737 to use a register and offset.
1738
1739
1740 \item \textbf{DW\-\_CFA\-\_def\-\_cfa\-\_offset\-\_sf} \\
1741 The \livetarg{chap:DWCFAdefcfaoffsetsf}{DW\-\_CFA\-\_def\-\_cfa\-\_offset\-\_sf} instruction takes a signed
1742 LEB128\addtoindexx{LEB128!signed} operand representing a factored offset. This instruction
1743 is identical to \livelink{chap:DWCFAdefcfaoffset}{DW\-\_CFA\-\_def\-\_cfa\-\_offset} except that the
1744 operand is signed and factored. The resulting offset is
1745 factored\_offset * \addtoindex{data\_alignment\_factor}.
1746 This operation
1747 is valid only if the current CFA rule is defined to use a
1748 register and offset.
1749
1750 \item \textbf{DW\-\_CFA\-\_def\-\_cfa\-\_expression} \\
1751 The \livetarg{chap:DWCFAdefcfaexpression}{DW\-\_CFA\-\_def\-\_cfa\-\_expression} 
1752 instruction takes a 
1753 \addtoindexx{exprloc class}
1754 single operand encoded as a 
1755 \livelink{chap:DWFORMexprloc}{DW\-\_FORM\-\_exprloc} value representing a
1756 DWARF expression. The required action is to establish that
1757 expression as the means by which the current CFA is computed.
1758
1759 \textit{See Section \refersec{chap:callframeinstructions} 
1760 regarding restrictions on the DWARF
1761 expression operators that can be used.}
1762
1763 \end{enumerate}
1764
1765 \subsubsection{Register Rule Instructions}
1766 \label{chap:registerruleinstructions}
1767 \begin{enumerate}[1. ]
1768
1769 \item \textbf{DW\-\_CFA\-\_undefined} \\
1770 The \livetarg{chap:DWCFAundefined}{DW\-\_CFA\-\_undefined} instruction takes a single unsigned
1771 LEB128\addtoindexx{LEB128!unsigned} operand that represents a register number. The required
1772 action is to set the rule for the specified register to
1773 ``undefined.''
1774
1775 \item \textbf{DW\-\_CFA\-\_same\-\_value} \\
1776 The \livetarg{chap:DWCFAsamevalue}{DW\-\_CFA\-\_same\-\_value} instruction takes a single unsigned
1777 LEB128 operand\addtoindexx{LEB128!unsigned} that represents a register number. The required
1778 action is to set the rule for the specified register to
1779 ``same value.''
1780
1781 \item \textbf{DW\-\_CFA\-\_offset} \\
1782 The \livetarg{chap:DWCFAoffset}{DW\-\_CFA\-\_offset} instruction takes two operands: a register
1783 number (encoded with the opcode) and an unsigned LEB128\addtoindexx{LEB128!unsigned}
1784 constant representing a factored offset. The required action
1785 is to change the rule for the register indicated by the
1786 register number to be an offset(N) rule where the value of
1787 N is 
1788 \textit{factored offset * \addtoindex{data\_alignment\_factor}}.
1789
1790 \item \textbf{DW\-\_CFA\-\_offset\-\_extended} \\
1791 The \livetarg{chap:DWCFAoffsetextended}{DW\-\_CFA\-\_offset\-\_extended} 
1792 instruction takes two unsigned LEB128\addtoindexx{LEB128!unsigned} 
1793 operands representing a register number and a factored
1794 offset. This instruction is identical to
1795 \livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset} 
1796 except for the encoding and size of the register operand.
1797
1798 \item \textbf{ DW\-\_CFA\-\_offset\-\_extended\-\_sf} \\
1799 The \livetarg{chap:DWCFAoffsetextendedsf}{DW\-\_CFA\-\_offset\-\_extended\-\_sf} 
1800 instruction takes two operands:
1801 an unsigned LEB128\addtoindexx{LEB128!unsigned} 
1802 value representing a register number and a
1803 signed LEB128 factored offset. This instruction is identical
1804 to \livelink{chap:DWCFAoffsetextended}{DW\-\_CFA\-\_offset\-\_extended} 
1805 except that the second operand is
1806 signed and factored. The resulting offset is 
1807 \textit{factored\_offset * \addtoindex{data\_alignment\_factor}}.
1808
1809 \item \textbf{DW\-\_CFA\-\_val\-\_offset} \\
1810 The \livetarg{chap:DWCFAvaloffset}{DW\-\_CFA\-\_val\-\_offset} 
1811 instruction takes two unsigned
1812 LEB128 operands\addtoindexx{LEB128!unsigned} representing a register number and a
1813 factored offset. The required action is to change the rule
1814 for the register indicated by the register number to be a
1815 val\_offset(N) rule where the value of N is 
1816 \textit{factored\_offset * \addtoindex{data\_alignment\_factor}}.
1817
1818 \item \textbf{DW\-\_CFA\-\_val\-\_offset\-\_sf} \\
1819 The \livetarg{chap:DWCFAvaloffsetsf}{DW\-\_CFA\-\_val\-\_offset\-\_sf} instruction takes two operands: an
1820 unsigned LEB128\addtoindexx{LEB128!unsigned} value representing a register number and a
1821 signed LEB128\addtoindexx{LEB128!signed} factored offset. This instruction is identical
1822 to \livelink{chap:DWCFAvaloffset}{DW\-\_CFA\-\_val\-\_offset} except that the second operand is signed
1823 and factored. The resulting offset is 
1824 \textit{factored\_offset * \addtoindex{data\_alignment\_factor}}.
1825
1826 \item \textbf{DW\-\_CFA\-\_register} \\
1827 The \livetarg{chap:DWCFAregister}{DW\-\_CFA\-\_register} 
1828 instruction takes two unsigned LEB128\addtoindexx{LEB128!unsigned}
1829 operands representing register numbers. The required action
1830 is to set the rule for the first register to be register(R)
1831 where R is the second register.
1832
1833 \item \textbf{DW\-\_CFA\-\_expression} \\
1834 The \livetarg{chap:DWCFAexpression}{DW\-\_CFA\-\_expression} 
1835 instruction takes two operands: an
1836 unsigned LEB128\addtoindexx{LEB128!unsigned} 
1837 value representing a register number, and
1838 a \livelink{chap:DWFORMblock}{DW\-\_FORM\-\_block} 
1839 value representing a DWARF expression. 
1840 The
1841 required action is to change the rule for the register
1842 indicated by the register number to be an expression(E)
1843 rule where E is the DWARF expression. That is, the DWARF
1844 expression computes the address. The value of the CFA is
1845 pushed on the DWARF evaluation stack prior to execution of
1846 the DWARF expression.
1847
1848 \textit{See Section \refersec{chap:callframeinstructions} 
1849 regarding restrictions on the DWARF
1850 expression operators that can be used.}
1851
1852 \needlines{7}
1853 \item \textbf{DW\-\_CFA\-\_val\-\_expression} \\
1854 The \livetarg{chap:DWCFAvalexpression}{DW\-\_CFA\-\_val\-\_expression} instruction takes two operands:
1855 an unsigned LEB128\addtoindexx{LEB128!unsigned} 
1856 value representing a register number, and
1857 a \livelink{chap:DWFORMblock}{DW\-\_FORM\-\_block} 
1858 value representing a DWARF expression. The
1859 required action is to change the rule for the register
1860 indicated by the register number to be a val\_expression(E)
1861 rule where E is the DWARF expression. That is, the DWARF
1862 expression computes the value of the given register. The value
1863 of the CFA is pushed on the DWARF evaluation stack prior to
1864 execution of the DWARF expression.
1865
1866 \textit{See Section \refersec{chap:callframeinstructions} 
1867 regarding restrictions on the DWARF
1868 expression operators that can be used.}
1869
1870 \item \textbf{ DW\-\_CFA\-\_restore} \\
1871 The \livetarg{chap:DWCFArestore}{DW\-\_CFA\-\_restore} instruction takes a single operand (encoded
1872 with the opcode) that represents a register number. The
1873 required action is to change the rule for the indicated
1874 register to the rule assigned it by the initial\_instructions
1875 in the CIE.
1876
1877 \item \textbf{DW\-\_CFA\-\_restore\-\_extended} \\
1878 The \livetarg{chap:DWCFArestoreextended}{DW\-\_CFA\-\_restore\-\_extended}
1879 instruction takes a single unsigned LEB128\addtoindexx{LEB128!unsigned} 
1880 operand that represents a register number. This
1881 instruction is identical to \livelink{chap:DWCFArestore}{DW\-\_CFA\-\_restore} except for the
1882 encoding and size of the register operand.
1883
1884 \end{enumerate}
1885
1886 \subsubsection{Row State Instructions}
1887 \label{chap:rowstateinstructions}
1888
1889 \textit{The next two instructions provide the ability to stack and
1890 retrieve complete register states. They may be useful, for
1891 example, for a compiler that moves \addtoindex{epilogue} code 
1892 into the
1893 body of a function.}
1894
1895
1896 \begin{enumerate}[1. ]
1897
1898 \item \textbf{DW\-\_CFA\-\_remember\-\_state} \\
1899 The \livetarg{chap:DWCFArememberstate}{DW\-\_CFA\-\_remember\-\_state} instruction takes no operands. The
1900 required action is to push the set of rules for every register
1901 onto an implicit stack.
1902
1903 \needlines{4}
1904 \item \textbf{DW\-\_CFA\-\_restore\-\_state} \\
1905 The \livetarg{chap:DWCFArestorestate}{DW\-\_CFA\-\_restore\-\_state} instruction takes no operands. The
1906 required action is to pop the set of rules off the implicit
1907 stack and place them in the current row.
1908
1909 \end{enumerate}
1910
1911 \subsubsection{Padding Instruction}
1912 \label{chap:paddinginstruction}
1913 \begin{enumerate}[1. ]
1914 \item \textbf{DW\-\_CFA\-\_nop} \\
1915 The \livetarg{chap:DWCFAnop}{DW\-\_CFA\-\_nop} instruction has no operands and no required
1916 actions. It is used as padding to make a CIE or FDE an
1917 appropriate size
1918
1919 \end{enumerate}
1920
1921 \subsection{Call Frame Instruction Usage} 
1922 \label{chap:callframeinstructionusage}
1923
1924 \textit{To determine the virtual unwind rule set for a given location
1925 (L1), one searches through the FDE headers looking at the
1926 initial\_location and address\_range values to see if L1 is
1927 contained in the FDE. If so, then:}
1928 \begin{enumerate}[1. ]
1929
1930 \item \textit{Initialize a register set by reading the
1931 initial\_instructions field of the associated CIE.}
1932
1933 \item \textit{Read and process the FDE\textquoteright s instruction
1934 sequence until a \livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}, 
1935 \livelink{chap:DWCFAsetloc}{DW\-\_CFA\-\_set\-\_loc}, or the
1936 end of the instruction stream is encountered.}
1937
1938 \item \textit{ If a \livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc} or \livelink{chap:DWCFAsetloc}{DW\-\_CFA\-\_set\-\_loc}
1939 instruction is encountered, then compute a new location value
1940 (L2). If L1 >= L2 then process the instruction and go back
1941 to step 2.}
1942
1943 \item \textit{ The end of the instruction stream can be thought
1944 of as a \livelink{chap:DWCFAsetloc}{DW\-\_CFA\-\_set\-\_loc} (initial\_location + address\_range)
1945 instruction. Note that the FDE is ill-formed if L2 is less
1946 than L1.}
1947
1948 \end{enumerate}
1949
1950 \textit{The rules in the register set now apply to location L1.}
1951
1952 \textit{For an example, see 
1953 Appendix \refersec{app:callframeinformationexample}.}
1954
1955
1956
1957 \subsection{Call Frame Calling Address}
1958 \label{chap:callframecallingaddress}
1959
1960 \textit{When unwinding frames, consumers frequently wish to obtain the
1961 address of the instruction which called a subroutine. This
1962 information is not always provided. Typically, however,
1963 one of the registers in the virtual unwind table is the
1964 Return Address.}
1965
1966 If a Return Address register is defined in the virtual
1967 unwind table, and its rule is undefined (for example, by
1968 \livelink{chap:DWCFAundefined}{DW\-\_CFA\-\_undefined}), then there is no return address and no
1969 call address, and the virtual unwind of stack activations
1970 is complete.
1971
1972 \textit{In most cases the return address is in the same context as the
1973 calling address, but that need not be the case, especially if
1974 the producer knows in some way the call never will return. The
1975 context of the 'return address' might be on a different line,
1976 in a different lexical \livelink{chap:lexicalblock}{block}, 
1977 or past the end of the calling
1978 subroutine. If a consumer were to assume that it was in the
1979 same context as the calling address, the unwind might fail.}
1980
1981 \textit{For architectures with constant-length instructions where
1982 the return address immediately follows the call instruction,
1983 a simple solution is to subtract the length of an instruction
1984 from the return address to obtain the calling instruction. For
1985 architectures with variable-length instructions (e.g.  x86),
1986 this is not possible. However, subtracting 1 from the return
1987 address, although not guaranteed to provide the exact calling
1988 address, generally will produce an address within the same
1989 context as the calling address, and that usually is sufficient.}
1990
1991
1992