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