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