This indexes letters f, g, and h.
[dwarf-doc.git] / dwarf5 / latexdoc / otherdebugginginformation.tex
index 636e5bb..29c7484 100644 (file)
@@ -240,7 +240,8 @@ object code. The matrix would have columns for:}
 \textit{Such a matrix, however, would be impractically large. We
 shrink it with two techniques. First, we delete from
 the matrix each row whose file, line, source column and
-discriminator information is identical with that of its
+\addtoindex{discriminator} information 
+is identical with that of its
 predecessors. Any deleted row would never be the beginning of
 a source statement. Second, we design a byte\dash coded language
 for a state machine and store a stream of bytes in the object
@@ -310,7 +311,7 @@ registers:
 The program\dash counter value corresponding to a machine instruction
 generated by the compiler. \\
 
-op\_index &
+\addtoindex{op\_index} &
 An unsigned integer representing the index of an operation within a VLIW
 instruction. The index of the first operation is 0. For non\dash VLIW
 architectures, this register will always be 0.
@@ -320,47 +321,48 @@ pointer that can reference any individual operation with the instruction
 stream. \\
 
 
-file &
+\addtoindex{file} &
 An unsigned integer indicating the identity of the source file
 corresponding to a machine instruction. \\
 
-line &
+\addtoindex{line} &
 An unsigned integer indicating a source line number. Lines are numbered
 beginning at 1. The compiler may emit the value 0 in cases where an
 instruction cannot be attributed to any source line. \\
 
-column &
+\addtoindex{column} &
 An unsigned integer indicating a column number within a source line.
 Columns are numbered beginning at 1. The value 0 is reserved to indicate
 that a statement begins at the ``left edge'' of the line. \\
 
-is\_stmt &
+\addtoindex{is\_stmt} &
 A boolean indicating that the current instruction is a recommended
 breakpoint location. A recommended breakpoint location 
 is intended to ``represent'' a line, a 
 statement and/or a semantically distinct subpart of a
 statement. \\
 
-basic\_block  &
+\addtoindex{basic\_block}  &
 A boolean indicating that the current instruction is the beginning of a
 \addtoindex{basic block}. \\
 
-end\_sequence &
+\addtoindex{end\_sequence} &
 A boolean indicating that the current address is that of the first byte after
-the end of a sequence of target machine instructions. end\_sequence
+the end of a sequence of target machine instructions. 
+\addtoindex{end\_sequence}
 terminates a sequence of lines; therefore other information in the same
 row is not meaningful. \\
 
-prologue\_end &
+\addtoindex{prologue\_end} &
 A boolean indicating that the current address is one (of possibly many)
 where execution should be suspended for an entry breakpoint of a
 function. \\
 
-epilogue\_begin &
+\addtoindex{epilogue\_begin} &
 A boolean indicating that the current address is one (of possibly many)
 where execution should be suspended for an exit breakpoint of a function. \\
 
-isa &
+\addtoindex{isa} &
 An unsigned integer whose value encodes the applicable
 instruction set architecture for the current instruction.
 The encoding of instruction sets should be shared by all
@@ -368,7 +370,7 @@ users of a given architecture. It is recommended that this
 encoding be defined by the ABI authoring committee for each
 architecture. \\
 
-discriminator &
+\addtoindex{discriminator} &
 An unsigned integer identifying the block to which the
 current instruction belongs. Discriminator values are assigned
 arbitrarily by the DWARF producer and serve to distinguish
@@ -387,11 +389,11 @@ op\_index & 0 \\
 file & 1 \\
 line & 1 \\
 column & 0 \\
-is\_stmt & determined by \addtoindex{default\_is\_stmt} in the line number program header \\
-basic\_block & ``false'' \addtoindexx{basic block} \\
-end\_sequence & ``false'' \\
-prologue\_end & ``false'' \\
-epilogue\_begin & ``false'' \\
+\addtoindex{is\_stmt} & determined by \addtoindex{default\_is\_stmt} in the line number program header \\
+\addtoindex{basic\_block} & ``false'' \addtoindexx{basic block} \\
+\addtoindex{end\_sequence} & ``false'' \\
+\addtoindex{prologue\_end} & ``false'' \\
+\addtoindex{epilogue\_begin} & ``false'' \\
 isa & 0 \\
 discriminator & 0 \\
 \end{tabular}
@@ -507,12 +509,21 @@ This parameter affects the meaning of the special opcodes. See below.
 This parameter affects the meaning of the special opcodes. See below.
 
 \item opcode\_base (ubyte) \\
-The number assigned to the first special opcode.
+The 
+\addtoindex{opcode\_base}
+number assigned to the first special opcode.
 
 \textit{Opcode base is typically one greater than the highest-numbered
+\addtoindex{opcode\_base}
 standard opcode defined for the specified version of the line
-number information (12 in DWARF Version 3 and Version 4, 9 in
-Version 2).  If opcode\_base is less than the typical value,
+number information (12 in 
+\addtoindex{DWARF Version 3} and 
+\addtoindexx{DWARF Version 4}
+Version 4, 9 in
+\addtoindexx{DWARF Version 2}
+Version 2).  
+If opcode\_base is less than the typical value,
+\addtoindex{opcode\_base}
 then standard opcode numbers greater than or equal to the
 opcode base are not used in the line number table of this unit
 (and the codes are treated as special opcodes). If opcode\_base
@@ -528,6 +539,7 @@ element corresponds to the opcode whose value
 is opcode\_base - 1.
 
 By increasing opcode\_base, and adding elements to this array,
+\addtoindex{opcode\_base}
 new standard opcodes can be added, while allowing consumers who
 do not know about these new opcodes to be able to skip them.
 
@@ -535,7 +547,9 @@ Codes for vendor specific extensions, if any, are described
 just like standard opcodes.
 
 \item include\_directories (sequence of path names) \\
-Entries in this sequence describe each path that was searched
+Entries 
+\addtoindexx{include\_directories}
+in this sequence describe each path that was searched
 for included source files in this compilation. (The paths
 include those directories specified explicitly by the user for
 the compiler to search and those the compiler searches without
@@ -550,7 +564,11 @@ the compilation is understood to be the zeroth entry and is
 not explicitly represented.
 
 \item  file\_names (sequence of file entries) \\
-Entries in this sequence describe source files that contribute
+Entries 
+\addtoindexx{file names}
+in 
+\addtoindexx{file\_names}
+this sequence describe source files that contribute
 to the line number information for this compilation unit or is
 used in other contexts, such as in a declaration coordinate or
 a macro file inclusion. Each entry consists of the following
@@ -621,15 +639,15 @@ Each ubyte special opcode has the following effect on the state machine:
 \item  Add a signed integer to the line register.
 
 \item  Modify the operation pointer by incrementing the
-address and op\_index registers as described below.
+address and \addtoindex{op\_index} registers as described below.
 
 \item  Append a row to the matrix using the current values
 of the state machine registers.
 
-\item  Set the basic\_block register to ``false.'' \addtoindexx{basic block}
-\item  Set the prologue\_end register to ``false.''
-\item  Set the epilogue\_begin register to ``false.''
-\item  Set the discriminator register to 0.
+\item  Set the \addtoindex{basic\_block} register to ``false.'' \addtoindexx{basic block}
+\item  Set the \addtoindex{prologue\_end} register to ``false.''
+\item  Set the \addtoindex{epilogue\_begin} register to ``false.''
+\item  Set the \addtoindex{discriminator} register to 0.
 
 \end{enumerate}
 
@@ -717,7 +735,8 @@ new op\_index =
 
 \textit{When the maximum\_operations\_per\_instruction field is 1,
 op\_index is always 0 and these calculations simplify to those
-given for addresses in DWARF Version 3.}
+given for addresses in 
+\addtoindex{DWARF Version 3}.}
 
 The amount to increment the line register is the line\_base plus
 the result of the adjusted opcode modulo the line\_range. That
@@ -784,14 +803,16 @@ actions performed by these opcodes are as follows:
 \item \textbf{DW\-\_LNS\-\_copy} \\
 The \livetarg{chap:DWLNScopy}{DW\-\_LNS\-\_copy} opcode takes no operands. It appends a row
 to the matrix using the current values of the state machine
-registers. Then it sets the discriminator register to 0,
-and sets the basic\_block, prologue\_end and epilogue\_begin
+registers. Then it sets the \addtoindex{discriminator} register to 0,
+and sets the \addtoindex{basic\_block}, 
+\addtoindex{prologue\_end} and 
+\addtoindex{epilogue\_begin}
 registers to ``false.''
 
 \item \textbf{DW\-\_LNS\-\_advance\-\_pc} \\
 The \livetarg{chap:DWLNSadvancepc}{DW\-\_LNS\-\_advance\-\_pc} opcode takes a single unsigned LEB128
 operand as the operation advance and modifies the address
-and op\_index registers as specified in 
+and \addtoindex{op\_index} registers as specified in 
 Section \refersec{chap:specialopcodes}.
 
 \item \textbf{DW\-\_LNS\-\_advance\-\_line} \\
@@ -856,7 +877,8 @@ use \livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc} ins
 
 \item \textbf{DW\-\_LNS\-\_set\-\_prologue\-\_end} \\
 The \livetarg{chap:DWLNSsetprologueend}{DW\-\_LNS\-\_set\-\_prologue\-\_end}
-opcode takes no operands. It sets the prologue\_end register
+opcode takes no operands. It sets the 
+\addtoindex{prologue\_end} register
 to ``true''.
 
 \textit{When a breakpoint is set on entry to a function, it is
@@ -873,7 +895,8 @@ the location(s) to use.}
 location; for example, the code might test for a special case
 and make a fast exit prior to setting up the frame.}
 
-\textit{Note that the function to which the prologue end applies cannot
+\textit{Note that the function to which the 
+\addtoindex{prologue end} applies cannot
 be directly determined from the line number information alone;
 it must be determined in combination with the subroutine
 information entries of the compilation (including inlined
@@ -882,7 +905,7 @@ subroutines).}
 
 \item \textbf{DW\-\_LNS\-\_set\-\_epilogue\-\_begin} \\
 The \livetarg{chap:DWLNSsetepiloguebegin}{DW\-\_LNS\-\_set\-\_epilogue\-\_begin} opcode takes no operands. It
-sets the epilogue\_begin register to ``true''.
+sets the \addtoindex{epilogue\_begin} register to ``true''.
 
 \textit{When a breakpoint is set on the exit of a function or execution
 steps over the last executable statement of a function, it is
@@ -892,14 +915,16 @@ local variables can still be examined). Debuggers generally
 cannot properly determine where this point is. This command
 allows a compiler to communicate the location(s) to use.}
 
-\textit{Note that the function to which the epilogue end applies cannot
+\textit{Note that the function to which the 
+\addtoindex{epilogue end} applies cannot
 be directly determined from the line number information alone;
 it must be determined in combination with the subroutine
 information entries of the compilation (including inlined
 subroutines).}
 
-\textit{In the case of a trivial function, both prologue end and
-epilogue begin may occur at the same address.}
+\textit{In the case of a trivial function, both 
+\addtoindex{prologue end} and
+\addtoindex{epilogue begin} may occur at the same address.}
 
 \item \textbf{DW\-\_LNS\-\_set\-\_isa} \\
 The \livetarg{chap:DWLNSsetisa}{DW\-\_LNS\-\_set\-\_isa} opcode takes a single
@@ -916,7 +941,8 @@ The extended opcodes are as follows:
 
 \item \textbf{DW\-\_LNE\-\_end\-\_sequence} \\
 The \livetarg{chap:DWLNEendsequence}{DW\-\_LNE\-\_end\-\_sequence} opcode takes no operands. It sets the
-end\_sequence register of the state machine to “true” and
+\addtoindex{end\_sequence}
+register of the state machine to “true” and
 appends a row to the matrix using the current values of the
 state-machine registers. Then it resets the registers to the
 initial values specified above 
@@ -983,7 +1009,7 @@ in the file register of the state machine.
 The \livetarg{chap:DWLNEsetdiscriminator}{DW\-\_LNE\-\_set\-\_discriminator}
 opcode takes a single
 parameter, an unsigned LEB128 integer. It sets the
-discriminator register to the new value.
+\addtoindex{discriminator} register to the new value.
 
 
 
@@ -1194,10 +1220,12 @@ across a call. If a callee wishes to use such a register, it
 saves the value that the register had at entry time in its call
 frame and restores it on exit. The code that allocates space
 on the call frame stack and performs the save operation is
-called the subroutine’s prologue, and the code that performs
+called the subroutine’s \addtoindex{prologue}, and the code that performs
 the restore operation and deallocates the frame is called its
-epilogue. Typically, the prologue code is physically at the
-beginning of a subroutine and the epilogue code is at the end.}
+\addtoindex{epilogue}. Typically, the 
+\addtoindex{prologue} code is physically at the
+beginning of a subroutine and the 
+\addtoindex{epilogue} code is at the end.}
 
 \textit{To be able to view or modify an activation that is not
 on the top of the call frame stack, the debugger must
@@ -1220,10 +1248,14 @@ special things.}
 
 \begin{itemize} % bullet list
 
-\item \textit{Prologue and epilogue code is not always in 
+\item \textit{Prologue 
+\addtoindexx{prologue}
+and 
+\addtoindex{epilogue} code is not always in 
 distinct block
 at the beginning and end of a subroutine. It is common
-to duplicate the epilogue code at the site of each return
+to duplicate the \addtoindex{epilogue} code 
+at the site of each return
 from the code. Sometimes a compiler breaks up the register
 save/unsave operations and moves them into the body of the
 subroutine to just where they are needed.}
@@ -1234,7 +1266,9 @@ frame. Sometimes they use a frame pointer register, sometimes
 not.}
 
 \item \textit{The algorithm to compute CFA changes as you progress through
-the prologue and epilogue code. (By definition, the CFA value
+the \addtoindex{prologue} 
+and \addtoindex{epilogue code}. 
+(By definition, the CFA value
 does not change.)}
 
 \item \textit{Some subroutines have no call frame.}
@@ -1351,7 +1385,10 @@ section called
 \addtoindex{.debug\_frame} section
 are aligned on a multiple of the address size relative to
 the start of the section and come in two forms: a Common
-Information Entry (CIE) and a Frame Description Entry (FDE).
+\addtoindexx{common information entry}
+Information Entry (CIE) and a 
+\addtoindexx{frame description entry}
+Frame Description Entry (FDE).
 
 \textit{If the range of code addresses for a function is not
 contiguous, there may be multiple CIEs and FDEs corresponding
@@ -1623,7 +1660,9 @@ is valid only if the current CFA rule is defined to use a
 register and offset.
 
 \item \textbf{DW\-\_CFA\-\_def\-\_cfa\-\_expression} \\
-The \livetarg{chap:DWCFAdefcfaexpression}{DW\-\_CFA\-\_def\-\_cfa\-\_expression} instruction takes a single
+The \livetarg{chap:DWCFAdefcfaexpression}{DW\-\_CFA\-\_def\-\_cfa\-\_expression} instruction takes a 
+\addtoindexx{exprloc class}
+single
 operand encoded as a \livelink{chap:DWFORMexprloc}{DW\-\_FORM\-\_exprloc} value representing a
 DWARF expression. The required action is to establish that
 expression as the means by which the current CFA is computed.
@@ -1749,7 +1788,8 @@ encoding and size of the register operand.
 
 \textit{The next two instructions provide the ability to stack and
 retrieve complete register states. They may be useful, for
-example, for a compiler that moves epilogue code into the
+example, for a compiler that moves \addtoindex{epilogue} code 
+into the
 body of a function.}