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