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