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