compression.tex
[dwarf-doc.git] / dwarf5 / latexdoc / otherdebugginginformation.tex
index 6126857..db3fa3f 100644 (file)
@@ -3,7 +3,8 @@
 % references to chapter 7 look like  {datarep:...}
 This section describes debugging information that is not
 represented in the form of debugging information entries and
-is not contained within a .debug\_info or .debug\_types section.
+is not contained within a \addtoindex{.debug\_info} or 
+\addtoindex{.debug\_types} section.
 
 In the descriptions that follow, these terms are used to
 specify the representation of DWARF sections:
@@ -20,6 +21,7 @@ Section \refersec{datarep:integerrepresentationnames}.
 \label{chap:acceleratedaccess}
 
 \textit{A debugger frequently needs to find the debugging information
+\addtoindexx{accelerated access}
 for a program entity defined outside of the compilation unit
 where the debugged program is currently stopped. Sometimes the
 debugger will know only the name of the entity; sometimes only
@@ -59,8 +61,12 @@ more condensed format.
 \subsection{Lookup by Name}
 
 For lookup by name, two tables are maintained in separate
-object file sections named .debug\_pubnames for objects and
-functions, and .debug\_pubtypes for types. Each table consists
+\addtoindex{accelerated access!by name}
+object file sections named 
+\addtoindex{.debug\_pubnames} for objects and
+functions, and 
+\addtoindex{.debug\_pubtypes}
+for types. Each table consists
 of sets of variable length entries. Each set describes the
 names of global objects and functions, or global types,
 respectively, whose definitions are represented by debugging
@@ -69,7 +75,8 @@ information entries owned by a single compilation unit.
 \textit{C++ member functions with a definition in the class declaration
 are definitions in every compilation unit containing the
 class declaration, but if there is no concrete out\dash of\dash line
-instance there is no need to have a .debug\_pubnames entry
+instance there is no need to have a 
+\addtoindex{.debug\_pubnames} entry
 for the member function.}
 
 Each set begins with a header containing four values:
@@ -81,18 +88,20 @@ not including the length field itself
 (see Section \refersec{datarep:locationdescriptions}).
 
 \item  version (uhalf) \\
-A version number 
+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 .debug\_info section of
+The offset 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 .debug\_info section
+The size in bytes of the contents of the 
+\addtoindex{.debug\_info} section
 generated to represent that compilation unit.
 \end{enumerate}
 
@@ -109,7 +118,9 @@ no following string).
 
 In the case of the name of a function member or static data
 member of a C++ structure, class or union, the name presented
-in the .debug\_pubnames section is not the simple name given
+in the 
+\addtoindex{.debug\_pubnames} 
+section is not the simple name given
 by the \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute of the referenced debugging
 information entry, but rather the fully qualified name of
 the data or function member.
@@ -117,7 +128,9 @@ the data or function member.
 \subsection{Lookup by Address}
 
 For lookup by address, a table is maintained in a separate
-object file section called .debug\_aranges. The table consists
+\addtoindex{accelerated access!by address}
+object file section called 
+\addtoindex{.debug\_aranges}. The table consists
 of sets of variable length entries, each set describing the
 portion of the program’s address space that is covered by
 a single compilation unit.
@@ -132,15 +145,15 @@ entries for that set, not including the length field itself
 (see Section \refersec{datarep:initiallengthvalues}).
 
 \item version (uhalf) \\
-A version number 
+A version number\addtoindexx{version number!address lookup table} 
 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
-This
-number is specific to the address lookup table and is
+This number is specific to the address lookup table and is
 independent of the DWARF version number.
 
 \item debug\_info\_offset (section offset) \\
 The offset from the
-beginning of the .debug\_info or .debug\_types section of the
+beginning of the \addtoindex{.debug\_info} or 
+\addtoindex{.debug\_types} section of the
 compilation unit header referenced by the set.
 
 \item address\_size (ubyte) \\
@@ -194,22 +207,25 @@ of the source files and to single step from line to line,
 or statement to statement.}
 
 Line number information generated for a compilation unit is
-represented in the .debug\_line section of an object file and
+represented in the 
+\addtoindex{.debug\_line} section of an object file and
 is referenced by a corresponding compilation unit debugging
 information entry 
 (see Section \refersec{chap:generalsubroutineandentrypointinformation}) 
-in the .debug\_info
+in the \addtoindex{.debug\_info}
 section.
 
 \textit{Some computer architectures employ more than one instruction
 set (for example, the ARM and MIPS architectures support
+\addtoindexx{ARM 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
-.debug\_line section as well.}
+\addtoindex{.debug\_line} section as well.}
 
 \textit{If space were not a consideration, the information provided
-in the .debug\_line section could be represented as a large
+in the \addtoindex{.debug\_line} 
+section could be represented as a large
 matrix, with one row for each instruction in the emitted
 object code. The matrix would have columns for:}
 
@@ -217,14 +233,15 @@ object code. The matrix would have columns for:}
 \item \textit{the source file name}
 \item \textit{the source line number}
 \item \textit{the source column number}
-\item \textit{whether this insruction is the beginning of a basic block}
+\item \textit{whether this insruction is the beginning of a \addtoindex{basic block}}
 \item \textit{and so on}
 \end{itemize}
 
 \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
@@ -259,12 +276,14 @@ A series of byte\dash coded
 line number information instructions representing
 one compilation unit. \\
 
-basic block &
+\addtoindex{basic block} &
  A sequence of instructions where only the first instruction may be a
 branch target and only the last instruction may transfer control. A
-procedure invocation is defined to be an exit from a basic block.
+procedure invocation is defined to be an exit from a 
+\addtoindex{basic block}.
 
-\textit{A basic block does not necessarily correspond to a specific source code
+\textit{A \addtoindex{basic block} does not 
+necessarily correspond to a specific source code
 construct.} \\
 
 sequence &
@@ -292,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.
@@ -302,47 +321,47 @@ 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  &
-A boolean indicating that the current instruction is the beginning of a basic 
-\nolink{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
 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
@@ -350,7 +369,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
@@ -369,8 +388,8 @@ op\_index & 0 \\
 file & 1 \\
 line & 1 \\
 column & 0 \\
-is\_stmt & determined by default\_is\_stmt in the line number program header \\
-basic\_block & ``false'' \\
+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'' \\
@@ -430,7 +449,7 @@ compilation unit, not including the unit\_length field itself
 (see Section \refersec{datarep:initiallengthvalues}). 
 
 \item version (uhalf) 
-A version number 
+A version number\addtoindexx{version number!line number information} 
 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
 This number is specific to
 the line number information and is independent of the DWARF
@@ -459,6 +478,7 @@ architectures, this field is 1, the 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.  
 
 \textit{A simple approach
@@ -492,8 +512,13 @@ The number assigned to the first special opcode.
 
 \textit{Opcode base is typically one greater than the highest-numbered
 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,
 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
@@ -607,10 +632,10 @@ address and 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.''
+\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{discriminator} register to 0.
 
 \end{enumerate}
 
@@ -698,7 +723,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
@@ -765,14 +791,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} \\
@@ -796,8 +824,11 @@ operands. It sets the is\_stmt register of the state machine
 to the logical negation of its current value.
 
 \item \textbf{DW\-\_LNS\-\_set\-\_basic\-\_block} \\
-The \livetarg{chap:DWLNSsetbasicblock}{DW\-\_LNS\-\_set\-\_basic\-\_block} opcode
-takes no operands. It sets the basic\_block register of the
+The \livetarg{chap:DWLNSsetbasicblock}{DW\-\_LNS\-\_set\-\_basic\-\_block}
+opcode
+\addtoindexx{basic block}
+takes no operands. 
+It sets the basic\_block register of the
 state machine to ``true.''
 
 
@@ -961,7 +992,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.
 
 
 
@@ -972,7 +1003,9 @@ gives some sample line number programs.}
 
 \section{Macro Information}
 \label{chap:macroinformation}
-\textit{Some languages, such as C and C++, provide a way to replace
+\textit{Some languages, such as 
+\addtoindex{C} and 
+addtoindex{C++}, provide a way to replace
 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
@@ -983,8 +1016,11 @@ the macro definition has been expanded, rather than as the
 programmer wrote it. The macro information table provides a way
 of preserving the original source in the debugging information.}
 
-As described in Section 3.1.1, the macro information for a
-given compilation unit is represented in the .debug\_macinfo
+As described in 
+Section \refersec{chap:normalandpartialcompilationunitentries},
+the macro information for a
+given compilation unit is represented in the 
+\addtoindex{.debug\_macinfo}
 section of an object file. The macro information for each
 compilation unit is represented as a series of “macinfo”
 entries. Each macinfo entry consists of a “type code” and
@@ -1114,7 +1150,8 @@ and should encode the value 0 in their line number operands.
 \subsection{General rules and restrictions}
 \label{chap:generalrulesandrestrictions}
 
-All macinfo entries within a .debug\_macinfo section for a
+All macinfo entries within a \addtoindex{.debug\_macinfo}
+section for a
 given compilation unit appear in the same order in which the
 directives were processed by the compiler.
 
@@ -1138,6 +1175,7 @@ user on the command line.
 
 
 \textit{Debuggers often need to be able to view and modify the state of any subroutine activation that is
+\addtoindexx{activation!call frame}
 on the call stack. An activation consists of:}
 
 \begin{itemize}
@@ -1317,7 +1355,9 @@ starting at the beginning address of each subroutine in
 the program.}
 
 The virtual unwind information is encoded in a self-contained
-section called .debug\_frame.  Entries in a .debug\_frame section
+section called 
+\addtoindex{.debug\_frame}.  Entries in a 
+\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).
@@ -1329,7 +1369,7 @@ to the parts of that function.}
 
 A Common Information Entry holds information that is shared
 among many Frame Description Entries. There is at least one
-CIE in every non-empty .debug\_frame section. A CIE contains
+CIE in every non-empty \addtoindex{.debug\_frame} section. A CIE contains
 the following fields, in order:
 
 \begin{enumerate}[1.]
@@ -1345,7 +1385,7 @@ integral multiple of the address size.
 A constant that is used to distinguish CIEs from FDEs.
 
 \item  version (ubyte) \\
-A version number 
+A version number\addtoindexx{version number!call frame information} 
 (see Section \refersec{datarep:callframeinformation}). 
 This number is specific to the call frame information
 and is independent of the DWARF version number.
@@ -1373,8 +1413,8 @@ which is needed to unwind a stack frame. For example, this
 might be information about dynamically allocated data which
 needs to be freed on exit from the routine.}
 
-\textit{Because the .debug\_frame section is useful independently of
-any .debug\_info section, the augmentation string always uses
+\textit{Because the \addtoindex{.debug\_frame} section is useful independently of
+any \addtoindex{.debug\_info} section, the augmentation string always uses
 UTF\dash 8 encoding.}
 
 \item  address\_size (ubyte) \\
@@ -1388,14 +1428,20 @@ its address size must match the address size here.
 The size of a segment selector in this CIE and any FDEs that
 use it, in bytes.
 
-\item  code\_alignment\_factor (unsigned LEB128) \\
-A constant that is factored out of all advance location
+\item  \addtoindex{code\_alignment\_factor} (unsigned LEB128) \\
+\addtoindex{code alignment factor}
+A 
+\addtoindexx{\textless caf\textgreater|see{code alignment factor}}
+constant that is factored out of all advance location
 instructions (see 
 Section \refersec{chap:rowcreationinstructions}).
 
 
-\item  data\_alignment\_factor (signed LEB128) \\
-A constant that is factored out of certain offset instructions
+\item  \addtoindex{data\_alignment\_factor} (signed LEB128) \\
+\addtoindexx{data alignment factor}
+A 
+\addtoindexx{\textless daf\textgreater|see{data alignment factor}}
+constant that is factored out of certain offset instructions
 (see below). The resulting value is  \textit{(operand *
 data\_alignment\_factor)}.
 
@@ -1432,7 +1478,8 @@ 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 .debug\_frame section that denotes
+A constant 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) \\
@@ -1511,7 +1558,8 @@ with the opcode) that represents a constant delta. The required
 action is to create a new table row with a location value that
 is computed by taking the current entry’s location value
 and adding the value of 
-\textit{delta * code\_alignment\_factor}. All
+\textit{delta * \addtoindex{code\_alignment\_factor}}. 
+All
 other values in the new row are initially identical to the
 current row
 
@@ -1551,7 +1599,7 @@ an unsigned LEB128 value representing a register number and a
 signed LEB128 factored offset. This instruction is identical
 to \livelink{chap:DWCFAdefcfa}{DW\-\_CFA\-\_def\-\_cfa} except that the second operand is signed
 and factored. The resulting offset is factored\_offset *
-data\_alignment\_factor.
+\addtoindex{data\_alignment\_factor}.
 
 
 \item \textbf{DW\-\_CFA\-\_def\-\_cfa\-\_register} \\
@@ -1578,7 +1626,8 @@ The \livetarg{chap:DWCFAdefcfaoffsetsf}{DW\-\_CFA\-\_def\-\_cfa\-\_offset\-\_sf}
 LEB128 operand representing a factored offset. This instruction
 is identical to \livelink{chap:DWCFAdefcfaoffset}{DW\-\_CFA\-\_def\-\_cfa\-\_offset} except that the
 operand is signed and factored. The resulting offset is
-factored\_offset * data\_alignment\_factor. This operation
+factored\_offset * \addtoindex{data\_alignment\_factor}.
+This operation
 is valid only if the current CFA rule is defined to use a
 register and offset.
 
@@ -1617,7 +1666,7 @@ constant representing a factored offset. The required action
 is to change the rule for the register indicated by the
 register number to be an offset(N) rule where the value of
 N is 
-\textit{factored offset * data\_alignment\_factor.}
+\textit{factored offset * \addtoindex{data\_alignment\_factor}}.
 
 \item \textbf{DW\-\_CFA\-\_offset\-\_extended} \\
 The \livetarg{chap:DWCFAoffsetextended}{DW\-\_CFA\-\_offset\-\_extended} instruction takes two unsigned
@@ -1631,7 +1680,7 @@ an unsigned LEB128 value representing a register number and a
 signed LEB128 factored offset. This instruction is identical
 to \livelink{chap:DWCFAoffsetextended}{DW\-\_CFA\-\_offset\-\_extended} except that the second operand is
 signed and factored. The resulting offset is 
-\textit{factored\_offset * data\_alignment\_factor}.
+\textit{factored\_offset * \addtoindex{data\_alignment\_factor}}.
 
 \item \textbf{DW\-\_CFA\-\_val\-\_offset} \\
 The \livetarg{chap:DWCFAvaloffset}{DW\-\_CFA\-\_val\-\_offset} instruction takes two unsigned
@@ -1639,7 +1688,7 @@ LEB128 operands representing a register number and a
 factored offset. The required action is to change the rule
 for the register indicated by the register number to be a
 val\_offset(N) rule where the value of N is 
-\textit{factored\_offset * data\_alignment\_factor}.
+\textit{factored\_offset * \addtoindex{data\_alignment\_factor}}.
 
 \item \textbf{DW\-\_CFA\-\_val\-\_offset\-\_sf} \\
 The \livetarg{chap:DWCFAvaloffsetsf}{DW\-\_CFA\-\_val\-\_offset\-\_sf} instruction takes two operands: an
@@ -1647,7 +1696,7 @@ unsigned LEB128 value representing a register number and a
 signed LEB128 factored offset. This instruction is identical
 to \livelink{chap:DWCFAvaloffset}{DW\-\_CFA\-\_val\-\_offset} except that the second operand is signed
 and factored. The resulting offset is 
-\textit{factored\_offset * data\_alignment\_factor}.
+\textit{factored\_offset * \addtoindex{data\_alignment\_factor}}.
 
 \item \textbf{DW\-\_CFA\-\_register} \\
 The \livetarg{chap:DWCFAregister}{DW\-\_CFA\-\_register} instruction takes two unsigned LEB128