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