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