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