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