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