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