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