Indexing o p q(none present) and r.
[dwarf-doc.git] / dwarf5 / latexdoc / otherdebugginginformation.tex
index a1e2126..9337eaa 100644 (file)
@@ -60,7 +60,9 @@ more condensed format.
 
 \subsection{Lookup by Name}
 
-For lookup by name, two tables are maintained in separate
+For lookup by name, 
+\addtoindexx{lookup!by name}
+two tables are maintained in separate
 \addtoindex{accelerated access!by name}
 object file sections named 
 \addtoindex{.debug\_pubnames} for objects and
@@ -127,7 +129,9 @@ the data or function member.
 
 \subsection{Lookup by Address}
 
-For lookup by address, a table is maintained in a separate
+For 
+\addtoindexx{lookup!by address}
+lookup by address, a table is maintained in a separate
 \addtoindex{accelerated access!by address}
 object file section called 
 \addtoindex{.debug\_aranges}. The table consists
@@ -195,6 +199,8 @@ multiple address range descriptors for that compilation unit.}
 \section{Line Number Information}
 \label{chap:linenumberinformation}
 \textit{A source\dash level debugger will need to know how to
+%FIXME: the see here is not 'see also'. Fix?
+\addtoindexx{line number information|see{statement list attribute}}
 associate locations in the source files with the corresponding
 machine instruction addresses in the executable object or
 the shared objects used by that executable object. Such an
@@ -216,8 +222,11 @@ in the \addtoindex{.debug\_info}
 section.
 
 \textit{Some computer architectures employ more than one instruction
-set (for example, the ARM and MIPS architectures support
+set (for example, the ARM 
 \addtoindexx{ARM instruction set architecture}
+and 
+MIPS architectures support
+\addtoindexx{MIPS instruction set architecture}
 a 32\dash bit as well as a 16\dash bit instruction set). Because the
 instruction set is a function of the program counter, it is
 convenient to encode the applicable instruction set in the
@@ -316,7 +325,8 @@ 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.
 
-The address and op\_index registers, taken together, form an operation
+The address and \addtoindex{op\_index} registers,
+taken together, form an operation
 pointer that can reference any individual operation with the instruction
 stream. \\
 
@@ -385,7 +395,7 @@ program, the state of the registers is:
 
 \begin{tabular}{lp{8cm}}
 address & 0 \\
-op\_index & 0 \\
+\addtoindex{op\_index} & 0 \\
 file & 1 \\
 line & 1 \\
 column & 0 \\
@@ -394,11 +404,12 @@ column & 0 \\
 \addtoindex{end\_sequence} & ``false'' \\
 \addtoindex{prologue\_end} & ``false'' \\
 \addtoindex{epilogue\_begin} & ``false'' \\
-isa & 0 \\
+\addtoindex{isa} & 0 \\
 discriminator & 0 \\
 \end{tabular}
 
-\textit{The isa value 0 specifies that the instruction set is the
+\textit{The 
+\addtoindex{isa} value 0 specifies that the instruction set is the
 architecturally determined default instruction set. This may
 be fixed by the ABI, or it may be specified by other means,
 for example, by the object file description.}
@@ -457,7 +468,7 @@ the line number information and is independent of the DWARF
 version number. 
 
 \item header\_length  \\
-The number of bytes following the header\_length field to the
+The number of bytes following the \addtoindex{header\_length} field to the
 beginning of the first byte of the line number program itself.
 In the 32\dash bit DWARF format, this is a 4\dash byte unsigned
 length; in the 64\dash bit DWARF format, this field is an
@@ -465,28 +476,37 @@ length; in the 64\dash bit DWARF format, this field is an
 (see Section \refersec{datarep:32bitand64bitdwarfformats}). 
 
 \item minimum\_instruction\_length (ubyte)  \\
+\addtoindexx{minimum\_instruction\_length}
 The size in bytes of the smallest target machine
 instruction. Line number program opcodes that alter
-the address and op\_index registers use this and
+the address and \addtoindex{op\_index} registers use this and
+\addtoindexx{maximum\_operations\_per\_instruction}
 maximum\-\_operations\-\_per\-\_instruction in their calculations. 
 
 \item maximum\_operations\_per\_instruction (ubyte) \\
-The maximum number of individual operations that may be
+The 
+\addtoindexx{maximum\_operations\_per\_instruction}
+maximum number of individual operations that may be
 encoded in an instruction. Line number program opcodes
-that alter the address and op\_index registers use this and
-minimum\_instruction\_length in their calculations.  For non-VLIW
-architectures, this field is 1, the op\_index register is always
+that alter the address and 
+\addtoindex{op\_index} registers use this and
+\addtoindex{minimum\_instruction\_length}
+in their calculations.
+For non-VLIW
+architectures, this field is 1, the \addtoindex{op\_index register} is always
 0, and the operation pointer is simply the address register.
 
 \item default\_is\_stmt (ubyte) \\
 \addtoindexx{default\_is\_stmt}
-The initial value of the is\_stmt register.  
+The initial value of the \addtoindex{is\_stmt} register.  
 
 \textit{A simple approach
 to building line number information when machine instructions
 are emitted in an order corresponding to the source program
-is to set default\_is\_stmt to ``true'' and to not change the
-value of the is\_stmt register within the line number program.
+is to set \addtoindex{default\_is\_stmt} 
+to ``true'' and to not change the
+value of the \addtoindex{is\_stmt} register 
+within the line number program.
 One matrix entry is produced for each line that has code
 generated for it. The effect is that every entry in the
 matrix recommends the beginning of each represented line as
@@ -498,20 +518,26 @@ the matrix for a line number; in this case, at least one entry
 (often but not necessarily only one) specifies a recommended
 breakpoint location for the line number. \livelink{chap:DWLNSnegatestmt}{DW\-\_LNS\-\_negate\-\_stmt}
 opcodes in the line number program control which matrix entries
-constitute such a recommendation and default\_is\_stmt might
+constitute such a recommendation and 
+\addtoindex{default\_is\_stmt} might
 be either ``true'' or ``false''. This approach might be
 used as part of support for debugging optimized code.}
 
 \item line\_base (sbyte) \\
+\addtoindexx{line\_base}
 This parameter affects the meaning of the special opcodes. See below.
 
 \item line\_range (ubyte) \\
+\addtoindexx{line\_range}
 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 
 \addtoindex{DWARF Version 3} and 
@@ -520,6 +546,7 @@ 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 +555,7 @@ that of the highest standard opcode and the first special
 opcode (not inclusive) are used for vendor specific extensions.}
 
 \item standard\_opcode\_lengths (array of ubyte) \\
+\addtoindexx{standard\_opcode\_lengths}
 This array specifies the number of LEB128 operands for each
 of the standard opcodes. The first element of the array
 corresponds to the opcode whose value is 1, and the last
@@ -535,6 +563,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.
 
@@ -542,7 +571,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
@@ -557,7 +588,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
@@ -570,10 +605,12 @@ path name of a source file. If the entry contains a file
 name or relative path name, the file is located relative
 to either the compilation directory (as specified by the
 \livelink{chap:DWATcompdir}{DW\-\_AT\-\_comp\-\_dir} attribute given in the compilation unit) or one
-of the directories listed in the include\_directories section.
+of the directories listed in the 
+\addtoindex{include\_directories} section.
 
 \item An unsigned LEB128 number representing the directory
-index of a directory in the include\_directories section.
+index of a directory in the 
+\addtoindex{include\_directories} section.
 
 
 \item An unsigned LEB128 number representing the
@@ -588,9 +625,11 @@ bytes of the file, or 0 if not available.
 The last entry is followed by a single null byte.
 
 The directory index represents an entry in the
-include\_directories section. The index is 0 if the file was
+\addtoindex{include\_directories} section. 
+The index is 0 if the file was
 found in the current directory of the compilation, 1 if it
-was found in the first directory in the include\_directories
+was found in the first directory in the 
+\addtoindex{include\_directories}
 section, and so on. The directory index is ignored for file
 names that represent full path names.
 
@@ -615,7 +654,9 @@ names field and define file names using the extended opcode
 As stated before, the goal of a line number program is to build
 a matrix representing one compilation unit, which may have
 produced multiple sequences of target machine instructions.
-Within a sequence, addresses (operation pointers) may only
+Within a sequence, addresses 
+\addtoindexx{operation pointer}
+(operation pointers) may only
 increase. (Line numbers may decrease in cases of pipeline
 scheduling or other optimization.)
 
@@ -627,7 +668,7 @@ 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
+\item  Modify the \addtoindex{operation pointer} by incrementing the
 address and \addtoindex{op\_index} registers as described below.
 
 \item  Append a row to the matrix using the current values
@@ -642,7 +683,7 @@ of the state machine registers.
 
 All of the special opcodes do those same seven things; they
 differ from one another only in what values they add to the
-line, address and op\_index registers.
+line, address and \addtoindex{op\_index} registers.
 
 
 \textit{Instead of assigning a fixed meaning to each special opcode,
@@ -665,40 +706,46 @@ the line register (a standard opcode provides an alternate
 way to decrease the line number) in return for the ability
 to add larger positive values to the address register. To
 permit this variety of strategies, the line number program
-header defines a line\_base field that specifies the minimum
+header defines a 
+\addtoindexx{line\_base}
+field that specifies the minimum
 value which a special opcode can add to the line register
 and a line\_range field that defines the range of values it
 can add to the line register.}
 
 
 A special opcode value is chosen based on the amount that needs
-to be added to the line, address and op\_index registers. The
+to be added to the line, address and \addtoindex{op\_index} registers.
+The
 maximum line increment for a special opcode is the value
-of the line\_base field in the header, plus the value of
+of the 
+\addtoindexx{line\_base}
+field in the header, plus the value of
 the line\_range field, minus 1 (line base + 
 line range - 1). 
 If the desired line increment is greater than the maximum
 line increment, a standard opcode must be used instead of a
-special opcode. The operation advance represents the number
-of operations to skip when advancing the operation pointer.
+special opcode. The \addtoindex{operation advance} represents the number
+of operations to skip when advancing the \addtoindex{operation pointer}.
 
 The special opcode is then calculated using the following formula:
 
-  opcode = ( \textit{desired line increment} - line\_base) +
-(line\_range * \textit{operation advance} ) + opcode\_base
+  opcode = ( \textit{desired line increment} - \addtoindex{line\_base}) +
+(\addtoindex{line\_range} * \textit{operation advance} ) + \addtoindex{opcode\_base}
 
 If the resulting opcode is greater than 255, a standard opcode
 must be used instead.
 
-When maximum\_operations\_per\_instruction is 1, the operation
+When \addtoindex{maximum\_operations\_per\_instruction} is 1, the operation
 advance is simply the address increment divided by the
-minimum\_instruction\_length.
+\addtoindex{minimum\_instruction\_length}.
 
 To decode a special opcode, subtract the opcode\_base from
 the opcode itself to give the \textit{adjusted opcode}. 
 The \textit{operation advance} 
 is the result of the adjusted opcode divided by the
-line\_range. The new address and op\_index values are given by
+line\_range. The new address and \addtoindex{op\_index} values
+are given by
 \begin{myindentpara}{1cm}
 
 \textit{adjusted opcode} = opcode – opcode\_base
@@ -710,40 +757,48 @@ new address =
 
 address +
 
-minimum\_instruction\_length *
-((op\_index + operation advance) / 
-maximum\_operations\_per\_instruction)
+\addtoindex{minimum\_instruction\_length} *
+((\addtoindex{op\_index} + \addtoindex{operation advance}) / 
+\addtoindex{maximum\_operations\_per\_instruction})
 \end{myindentpara}
 new op\_index =
 
 \begin{myindentpara}{1cm}
-(op\_index + operation advance) \% maximum\_operations\_per\_instruction
+(\addtoindex{op\_index} + \addtoindex{operation advance}) \% 
+\addtoindex{maximum\_operations\_per\_instruction}
 \end{myindentpara}
 
 \end{myindentpara}
 
-\textit{When the maximum\_operations\_per\_instruction field is 1,
+\textit{When the \addtoindex{maximum\_operations\_per\_instruction} field is 1,
 op\_index is always 0 and these calculations simplify to those
 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
+The amount to increment the line register is the 
+\addtoindex{line\_base} plus
+the result of the 
+\addtoindex{adjusted opcode} modulo the 
+\addtoindex{line\_range}. That
 is,
 
 \begin{myindentpara}{1cm}
-line increment = line\_base + (adjusted opcode \% line\_range)
+line increment = \addtoindex{line\_base} + (adjusted opcode \% \addtoindex{line\_range})
 \end{myindentpara}
 
-\textit{As an example, suppose that the opcode\_base is 13, line\_base
-is -3, line\_range is 12, minimum\_instruction\_length is 1
-and maximum\_operations\_per\_instruction is 1. This means that
+\textit{As an example, suppose that the opcode\_base is 13, 
+\addtoindex{line\_base}
+is -3, \addtoindex{line\_range} is 12, 
+\addtoindex{minimum\_instruction\_length} is 1
+and 
+\addtoindex{maximum\_operations\_per\_instruction} is 1. 
+This means that
 we can use a special opcode whenever two successive rows in
 the matrix have source line numbers differing by any value
 within the range [-3, 8] and (because of the limited number
 of opcodes available) when the difference between addresses
 is within the range [0, 20], but not all line advances are
-available for the maximum operation advance (see below).}
+available for the maximum \addtoindex{operation advance} (see below).}
 
 \textit{The opcode mapping would be:}
 % FIXME: This should be a tabular or the like, not a verbatim
@@ -777,8 +832,8 @@ available for the maximum operation advance (see below).}
 
 
 \textit{There is no requirement that the expression 
-255 - line\_base + 1 be an integral multiple of
-line\_range. }
+255 - \addtoindex{line\_base} + 1 be an integral multiple of
+\addtoindex{line\_range}. }
 
 \subsubsection{Standard Opcodes}
 \label{chap:standardopcodes}
@@ -800,7 +855,7 @@ 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
+operand as the \addtoindex{operation advance} and modifies the address
 and \addtoindex{op\_index} registers as specified in 
 Section \refersec{chap:specialopcodes}.
 
@@ -821,7 +876,7 @@ register of the state machine.
 
 \item \textbf{DW\-\_LNS\-\_negate\-\_stmt} \\
 The \livetarg{chap:DWLNSnegatestmt}{DW\-\_LNS\-\_negate\-\_stmt} opcode takes no
-operands. It sets the is\_stmt register of the state machine
+operands. It sets the \addtoindex{is\_stmt} register of the state machine
 to the logical negation of its current value.
 
 \item \textbf{DW\-\_LNS\-\_set\-\_basic\-\_block} \\
@@ -856,7 +911,7 @@ address register of the state machine and sets the op\_index
 register to 0. This is the only standard opcode whose operand
 is \textbf{not} a variable length number. It also does 
 \textbf{not} multiply the
-operand by the minimum\_instruction\_length field of the header.
+operand by the \addtoindex{minimum\_instruction\_length} field of the header.
 
 \textit{Existing assemblers cannot emit \livelink{chap:DWLNSadvancepc}{DW\-\_LNS\-\_advance\-\_pc} or special
 opcodes because they cannot encode LEB128 numbers or judge when
@@ -917,7 +972,8 @@ subroutines).}
 
 \item \textbf{DW\-\_LNS\-\_set\-\_isa} \\
 The \livetarg{chap:DWLNSsetisa}{DW\-\_LNS\-\_set\-\_isa} opcode takes a single
-unsigned LEB128 operand and stores that value in the isa
+unsigned LEB128 operand and stores that value in the 
+\addtoindex{isa}
 register of the state machine.
 \end{enumerate}
 
@@ -964,7 +1020,8 @@ path name of a source file. If the entry contains a file
 name or a relative path name, the file is located relative
 to either the compilation directory (as specified by the
 \livelink{chap:DWATcompdir}{DW\-\_AT\-\_comp\-\_dir} attribute given in the compilation unit)
-or one of the directories in the include\_directories section.
+or one of the directories in the 
+\addtoindex{include\_directories} section.
 
 \item An unsigned LEB128 number representing the directory index
 of the directory in which the file was found.  
@@ -979,10 +1036,11 @@ not available.
 \end{enumerate}
 
 The directory index represents an entry in the
-include\_directories section of the line number program
+\addtoindex{include\_directories} section of the line number program
 header. The index is 0 if the file was found in the current
 directory of the compilation, 1 if it was found in the first
-directory in the include\_directories section, and so on. The
+directory in the \addtoindex{include\_directories} section,
+and so on. The
 directory index is ignored for file names that represent full
 path names.
 
@@ -1012,6 +1070,7 @@ gives some sample line number programs.}
 \textit{Some languages, such as 
 \addtoindex{C} and 
 addtoindex{C++}, provide a way to replace
+\addtoindex{macro information}
 text in the source program with macros defined either in the
 source file itself, or in another file included by the source
 file.  Because these macros are not themselves defined in the
@@ -1037,7 +1096,7 @@ code of 0.
 \subsection{Macinfo Types}
 \label{chap:macinfotypes}
 
-The valid macinfo types are as follows:
+The valid \addtoindex{macinfo types} are as follows:
 
 \begin{tabular}{ll}
 \livelink{chap:DWMACINFOdefine}{DW\-\_MACINFO\-\_define} 
@@ -1070,8 +1129,9 @@ symbol that was undefined at the indicated source line.
 
 In the case of a \livelink{chap:DWMACINFOdefine}{DW\-\_MACINFO\-\_define} entry, the value of this
 string will be the name of the macro symbol that was defined
-at the indicated source line, followed immediately by the macro
-formal parameter list including the surrounding parentheses (in
+at the indicated source line, followed immediately by the 
+\addtoindex{macro formal parameter list}
+including the surrounding parentheses (in
 the case of a function-like macro) followed by the definition
 string for the macro. If there is no formal parameter list,
 then the name of the defined macro is followed directly by
@@ -1374,7 +1434,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