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