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