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