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