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