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