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