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