Indexing letter 's'.
[dwarf-doc.git] / dwarf5 / latexdoc / otherdebugginginformation.tex
index 4d32fb4..c0172b7 100644 (file)
@@ -9,12 +9,19 @@ is not contained within a \addtoindex{.debug\_info} or
 In the descriptions that follow, these terms are used to
 specify the representation of DWARF sections:
 
-Initial length, section offset and section length, which are
+Initial length, section offset and 
+\addtoindex{section length}, which are
 defined in 
 Sections \refersec{datarep:locationdescriptions} and 
 \refersec{datarep:32bitand64bitdwarfformats}.
 
-Sbyte, ubyte, uhalf, and uword, which are defined in 
+Sbyte, 
+\addtoindex{ubyte}, 
+\addtoindex{uhalf}, and 
+\addtoindex{uword}, 
+which 
+\addtoindexx{sbyte}
+are defined in 
 Section \refersec{datarep:integerrepresentationnames}.
 
 \section{Accelerated Access}
@@ -90,19 +97,28 @@ not including the length field itself
 (see Section \refersec{datarep:locationdescriptions}).
 
 \item  version (uhalf) \\
-A version number\addtoindexx{version number!name lookup table}\addtoindexx{version number!type lookup table} 
+A version number
+\addtoindexx{version number!name lookup table}
+\addtoindexx{version number!type lookup table} 
 (see Section \refersec{datarep:namelookuptables}). 
 This number is specific
 to the name lookup table and is independent of the DWARF
 version number.
 
 \item debug\_info\_offset (section offset) \\
-The offset from the beginning of the 
+The 
+\addtoindexx{section offset!in .debug\_pubtypes header}
+offset 
+\addtoindexx{section offset!in .debug\_pubtypes header}
+from the beginning of the 
 \addtoindex{.debug\_info} section of
 the compilation unit header referenced by the set.
 
 \item debug\_info\_length (section length) \\
-The size in bytes of the contents of the 
+\addtoindexx{section length!in .debug\_pubnames header}
+The 
+\addtoindexx{section length!in .debug\_pubtypes header}
+size in bytes of the contents of the 
 \addtoindex{.debug\_info} section
 generated to represent that compilation unit.
 \end{enumerate}
@@ -156,12 +172,16 @@ independent of the DWARF version number.
 
 \item debug\_info\_offset (section offset) \\
 The offset from the
+\addtoindexx{section offset!in .debug\_pubnames header}
 beginning of the \addtoindex{.debug\_info} or 
 \addtoindex{.debug\_types} section of the
 compilation unit header referenced by the set.
 
 \item address\_size (ubyte) \\
-The size of an address in bytes on
+The \addtoindex{size of an address}
+in 
+\addtoindexx{ubyte}
+bytes on
 \addtoindexx{address\_size}
 the target architecture. For 
 \addtoindexx{address space!segmented}
@@ -169,7 +189,10 @@ segmented addressing, this is
 the size of the offset portion of the address.
 
 \item segment\_size (ubyte) \\
-The size of a segment selector in
+The size of a segment selector 
+\addtoindexx{ubyte}
+in
+\addtoindexx{segment\_size}
 bytes on the target architecture. If the target system uses
 a flat address space, this value is 0.
 
@@ -182,7 +205,9 @@ segment selector, the beginning address within that segment
 of a range of text or data covered by some entry owned by
 the corresponding compilation unit, followed by the non\dash zero
 length of that range. A particular set is terminated by an
-entry consisting of three zeroes. When the segment\_size value
+entry consisting of three zeroes. 
+When the 
+\addtoindex{segment\_size} value
 is zero in the header, the segment selector is omitted so that
 each descriptor is just a pair, including the terminating
 entry. By scanning the table, a debugger can quickly decide
@@ -222,8 +247,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
@@ -322,7 +350,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. \\
 
@@ -391,7 +420,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 \\
@@ -464,7 +493,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
@@ -472,17 +501,24 @@ 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) \\
@@ -512,18 +548,22 @@ constitute such a recommendation and
 be either ``true'' or ``false''. This approach might be
 used as part of support for debugging optimized code.}
 
-\item line\_base (sbyte) \\
+\item line\_base (\addtoindex{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.
+This 
+\addtoindexx{ubyte}
+parameter affects the meaning of the special opcodes. See below.
 
 \item opcode\_base (ubyte) \\
 The 
 \addtoindex{opcode\_base}
-number assigned to the first special opcode.
+number
+\addtoindexx{ubyte}
+ assigned to the first special opcode.
 
 \textit{Opcode base is typically one greater than the highest-numbered
 \addtoindex{opcode\_base}
@@ -643,7 +683,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.)
 
@@ -655,7 +697,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
@@ -670,7 +712,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,
@@ -702,7 +744,8 @@ 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 
 \addtoindexx{line\_base}
@@ -711,8 +754,8 @@ 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:
 
@@ -722,15 +765,16 @@ The special opcode is then calculated using the following formula:
 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
@@ -742,19 +786,20 @@ 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}.}
@@ -782,7 +827,7 @@ 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
@@ -839,7 +884,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}.
 
@@ -895,7 +940,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
@@ -1054,6 +1099,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
@@ -1079,7 +1125,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} 
@@ -1112,8 +1158,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
@@ -1480,11 +1527,16 @@ UTF\dash 8 encoding.}
 The size of a target address
 \addtoindexx{address\_size}
 in this CIE and any FDEs that
+\addtoindexx{ubyte}
 use it, in bytes. If a compilation unit exists for this frame,
 its address size must match the address size here.
 
 \item  segment\_size (ubyte) \\
-The size of a segment selector in this CIE and any FDEs that
+The 
+\addtoindexx{segment\_size}
+size 
+\addtoindexx{ubyte}
+of a segment selector in this CIE and any FDEs that
 use it, in bytes.
 
 \item  \addtoindex{code\_alignment\_factor} (unsigned LEB128) \\
@@ -1537,24 +1589,37 @@ plus the value of length must be an integral multiple of the
 address size.
 
 \item   CIE\_pointer (4 or 8 bytes, see Section \refersec{datarep:32bitand64bitdwarfformats}) \\
-A constant offset into the \addtoindex{.debug\_frame}
+A constant 
+\addtoindexx{section offset!in FDE header}
+offset into the \addtoindex{.debug\_frame}
 section that denotes
 the CIE that is associated with this FDE.
 
 \item  initial\_location (segment selector and target address) \\
-The address of the first location associated with this table
-entry. If the segment\_size field of this FDE's CIE is non-zero,
+The 
+\addtoindexx{initial\_location}
+address of the first location associated with this table
+entry. 
+If the \addtoindex{segment\_size} field of this FDE's CIE is non-zero,
 the initial location is preceded by a segment selector of
 the given length.
 
 \item  address\_range (target address) \\
-The number of bytes of program instructions described by this entry.
+The 
+\addtoindexx{address\_range}
+number 
+\addtoindexx{target address}
+of bytes of program instructions described by this entry.
 
 \item instructions (array of ubyte) \\
-A sequence of table defining instructions that are described below.
+A 
+\addtoindexx{ubyte}
+sequence of table defining instructions that are described below.
 
 \item 6. padding (array of ubyte) \\
-Enough \livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop} instructions to make the size of this
+Enough \livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop} instructions 
+to make the size of this
+\addtoindexx{ubyte}
 entry match the length value above.
 \end{enumerate}
 
@@ -1601,12 +1666,15 @@ and \livelink{chap:DWCFAvalexpression}{DW\-\_CFA\-\_val\-\_expression}.}
 \begin{enumerate}[1.]
 
 \item \textbf{DW\-\_CFA\-\_set\-\_loc} \\
-The \livetarg{chap:DWCFAsetloc}{DW\-\_CFA\-\_set\-\_loc} instruction takes a single operand that
+The \livetarg{chap:DWCFAsetloc}{DW\-\_CFA\-\_set\-\_loc} instruction 
+takes a single operand that
 represents a target address. The required action is to create a
 new table row using the specified address as the location. All
 other values in the new row are initially identical to the
 current row. The new location value is always greater than
-the current one. If the segment\_size field of this FDE's CIE
+the current one. 
+If the \addtoindex{segment\_size} field of this FDE's 
+\addtoindex{CIE}
 is non- zero, the initial location is preceded by a segment
 selector of the given length.