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